Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/score-spec/docs
Docs for Score Specification.
https://github.com/score-spec/docs
Last synced: 9 days ago
JSON representation
Docs for Score Specification.
- Host: GitHub
- URL: https://github.com/score-spec/docs
- Owner: score-spec
- License: apache-2.0
- Created: 2022-11-08T23:05:09.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T13:06:10.000Z (2 months ago)
- Last Synced: 2024-10-29T15:56:30.455Z (2 months ago)
- Language: HTML
- Homepage: https://docs.score.dev/docs/
- Size: 21.5 MB
- Stars: 6
- Watchers: 2
- Forks: 12
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
## Docs
This section covers how to build the documentation site with Hugo.
For information on Score's style guide see the [Style guide](styles/style-guide.md).
### Running the website locally
#### `yarn`
We use `yarn` (for MacOS: `brew install yarn`) as a package manager to ensure the versions of Hugo and associated tools are up to date. All commands that execute those tools are prefixed with `yarn run` or are aliased in the `package.json` file.
To install the packages:
```
yarn install
```
To run the server locally:
```
yarn build
OR
yarn run hugo server
```
And then view it at .
#### `score-compose`
You can [install `score-compose`](https://docs.score.dev/docs/score-implementation/score-compose/installation/) and then build and run this hugo website as a container:
```
score-compose init --no-sample
score-compose generate score.yaml --build main=.
docker compose up --build -d
curl $(score-compose resources get-outputs dns.default#score-docs.dns --format '{{ .host }}:8080/docs/')
```
### Deployment
This site is currently deployed through Github Pages with a CNAME directing `docs.score.dev` to `score-spec.github.io`. The DNS configuration is managed by Humanitec.
### Format docs
The following section covers how to format and lint prose.
### Formatters and linters
This project uses the [dprint](https://dprint.dev/overview/) to format documentation. dprint is a command line application that automatically formats code.
Use `dprint` to format your documentation.
```bash
yarn fmt
```
Example output.
```bash
$ yarn fmt
Formatted 1 file.
✨ Done in 0.13s.
```
This project uses the [Vale](https://vale.sh) with a [Vale-compatible implementation of the Google Developer Documentation Style Guide](https://github.com/errata-ai/Google).
On MacOS, install it through `brew install vale`.
For example, to lint a document run:
```bash
vale sync
vale styles/style-guide.md
```
Example output.
```bash
styles/style-guide.md
40:71 error Did you really mean Vale.Spelling
'inclusivity'?
✖ 1 error, 0 warnings and 0 suggestions in 1 file.
```
To lint all documents, run `yarn lint`.
## Troubleshooting documentation site builds
This section covers common build issues with Hugo.
### Failed to resolve output format `print`
When building the server, you may receive the following error message.
```bash
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`](https://gohugo.io/commands/hugo_server/) is stored at `$TMPDIR/hugo_cache`.
```bash
rm -rf $TMPDIR/hugo_cache
```
### `package-lock.json` locked files
When running `yarn`, you may receive the following error message.
```bash
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.
```bash
rm package-lock.json
```
You can find our documentation at [docs.score.dev](https://docs.score.dev/docs/).
### 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](CONTRIBUTING.md) for more information.
### Roadmap
See [Roadmap](roadmap.md). You can [submit an idea](https://github.com/score-spec/spec/issues/new) anytime.
### License
[](https://opensource.org/licenses/Apache-2.0)
### Code of conduct
[](CODE_OF_CONDUCT.md)