Vale
Vale is a tool that checks the content you write, as well as reports problems based on a set of rules and guidelines. You should follow the Vaadin documentation guidelines when contributing to the Vaadin documentation.
Pull Request Reviews
The Vale rules are checked automatically during a pull request review, after you commit and push changes to the GitHub repository.
If the Vale check fails — that is if it produces errors, warnings, or suggestions — you can see those in the Files changed tab.
An annotation shows below the line where Vale detected an issue.
You should always fix any errors that Vale reports before you mark a pull request as ready for review. Try to resolve as many warnings and suggestions as you can, although sometimes it’s acceptable, or even preferable, to ignore warnings and suggestions. For instance, the use of passive voice or future tense may be appropriate sometimes.
If you’re unsure how to fix an issue, you can ask for help from the documentation maintainers, or wait for someone to perform the required language check — one of the next steps in a pull request that’s ready for review.
Use Locally
Vale is easiest to use together with VS Code and the Vale extension. You can also run Vale directly from the command-line by giving one or more AsciiDoc files as parameters:
$ vale page-filename.adoc
page-filename.adoc
154:32 suggestion 'simply' is a weasel word. Vaadin.Weasel
✖ 0 errors, 0 warnings and 1 suggestions in 1 file.See the Vale documentation for instructions on installing Vale on macOS, Windows, or Linux.
Configuration
Vale is configured with the .vale.ini file in the root of the vaadin/docs project. A separate .vale-pr.ini configuration is used for pull requests. See the Vale Configuration documentation page to learn more.
Vocabulary
If you get false spelling errors from the Vale.Spelling rule (e.g., for the word "Vaadin"), you can add words to the .github/styles/Vocab/accept.txt file to suppress them. See the Vale Vocabularies documentation page to learn more.
Style Rules
The writing style rules are located in the .github/styles/Vaadin folder. Each rule is in a separate YAML file. See the Vale Styles documentation page to learn how to create new rules.
Occasionally, you might need to suppress a rule for certain parts of text. You can do that with a specific comment syntax. For example, if you want to use future tense, you can suppress the Vaadin.Will rule like so:
pass:[<!-- vale Vaadin.Will = NO -->]
If you really want it, it will be possible.
pass:[<!-- vale Vaadin.Will = YES -->]
Rules that use scope: raw (e.g., Vaadin.SourceCode) can’t be suppressed with these comments.