Avalanche-Docs uses a variety of linting and style checking programs including
- Vale
- Markdownlint
- Uses Super-Linter as a GitHub Action. This pulls in a few other linting tools but they're all turned off.
The overall config is .vale.ini. You can find the individual style
in .github/styles.
Look at .markdownlint.json.
Edit .github/workflows/ci.yml. Add the file or folder to the files
tag in the Vale task.
For readability, the CI only print errors. You absolutely should address warnings and suggestions in your docs, so please run the tools locally before committing to the repository.
Local install instructions
Run the tool with vale <filename>. You can provide a file or a directory.
The Vale VS Code Extension
is quite useful for visualizing style errors in-line.
To run locally, install the Markdownlint CLI
Run with markdownlint <filename>. There is also an extension to add it to
VS Code.
There are two paths to resolving issues, edit you doc or update the linting rules. For example:
Did you really mean 'homescreen'? Vale.Spelling
You can correct the spelling by splitting homescreen into home screen or add a new rule.
Vale.Spelling tells you that you would need to add a new approved spelling. You can find
instructions to do so below.
To add a new spelling rule, add the word to .github/styles/Vocab/Products/accept.txt. The file is case-sensitive and plurals/other tenses count as separate words.
To block a specific word from appearing in the repository, add the word to .github/styles/Vocab/Products/reject.txt.
If you would like to enforce a specific product name such as Avalanche-CLI as opposed to
avalanche-cli or Avalanche CLI, you create a new regular expression substitution pattern in
either
.github/styles/custom/ProductCapitalization.yml
or .github/styles/custom/RejectForms.yml`.
If you'd like to add an exception to a Vale rule, navigate to the rule in .github/styles and add an
entry under exceptions. See
.github/styles/GoogleModified/Headings.yml for an example.
If you would like to ignore a Markdownlint rule inline (such as for a line length violation within a code block), you can add this style of comment:
<!-- markdownlint-disable MD013 -->
<Rule violating code goes here>
<!-- markdownlint-enable MD013 -->
Make sure to replace MD013 with the
rule you'd like to override.
If you would like to turn off vale inline, you can add this style of comment:
<!-- vale off -->
This is some text
more text here...
<!-- vale on -->
Please don't ignore line length violations by ignoring Markdownlint rule MD013. The only place it is generally acceptable to do so is in code blocks. Generally, markdown text isn't affected by breaking text up with single newlines. To assist with managing line lengths, you may want to use Rewrap or another similar markdown line-wrapping tool.
To use Rewrap, highlight the section of code you want to wrap and press ⌘/alt + q to smartly wrap
your lines. The one downside to Rewrap is that it doesn't properly break bold text. You need
to manually add ** to both the end of your wrapped line and the start of the next line.