Docs

This section covers how to build the documentation site with Hugo. For information on Score's style guide see the Style guide.

Running the website locally

Building and running the site locally requires a recent extended version of Hugo. You can find out more about how to install Hugo for your environment in our Getting started guide.

From the repo root folder, run:

To use yarn.

yarn build

To use Hugo.

hugo server -D

Format docs

The following section covers how to format and lint prose.

Formatters and linters

This project uses the dprint to format documentation. dprint is a command line application that automatically formats code.

Use dprint to format your documentation.

yarn fmt

Example output.

$ dprint fmt
Formatted 1 file.
✨  Done in 0.13s.

This project uses the Vale with a Vale-compatible implementation of the Google Developer Documentation Style Guide.

To lint your doc run:

yarn fmt /path/to/your/file.md

For example, to lint this document run:

vale sync
vale styles/style-guide.md

Example output.

 styles/style-guide.md
 40:71  error  Did you really mean             Vale.Spelling 
               'inclusivity'?                                

✖ 1 error, 0 warnings and 0 suggestions in 1 file.

Troubleshooting documentation site builds

This section covers common build issues with Hugo.

Extended version of Hugo

As you run the website locally, you may run into the following error:

➜ hugo server

INFO 2021/01/21 21:07:55 Using config file:
Building sites … INFO 2021/01/21 21:07:55 syncing static files to /
Built in 288 ms
Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache

This error occurs if you have not installed the extended version of Hugo. See this section of the user guide for instructions on how to install Hugo.

Or you may encounter the following error:

➜ hugo server

Error: failed to download modules: binary with name "go" not found

This error occurs if you have not installed the go programming language on your system. See this section of the user guide for instructions on how to install go.

Failed to resolve output format print

When building the server, you may receive the following error message.

Error: from config: failed to resolve output format "print" from site config
error Command failed with exit code 255.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

To resolve this issue, delete the temporary Hugo cache directory. By default, -cacheDir is stored at $TMPDIR/hugo_cache.

rm -rf $TMPDIR/hugo_cache

package-lock.json locked files

When running yarn, you may receive the following error message.

warning package-lock.json found. Your project contains lock files generated by tools other than Yarn. It is advised not to mix package managers in order to avoid resolution inconsistencies caused by unsynchronized lock files. To clear this warning, remove package-lock.json.

To resolve this issue, delete the package-lock.json file.

rm package-lock.json

You can find our documentation at docs.score.dev.

Contribute

If you have a suggestion to improve our documentation, please fork the repo and create a pull request. You can also open an issue with the tag enhancement.

1. Fork the Project.
2. Create your Feature Branch. git checkout -b feature/feature-name
3. Commit your Changes. git commit -s -m "Add some amazing documentation enhancement"
4. Push to the Branch. git push origin feature/feature-name
5. Open a Pull Request.

Read CONTRIBUTING for more information.

Roadmap

See Roadmap. You can submit an idea anytime.

License

Code of conduct