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.
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.
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.
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.
The writing style rules are located in the
.githug/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:
// tag::start pass:[<!-- vale Vaadin.Will = NO -->] // end::start If you really want it, it will be possible. // tag::stop pass:[<!-- vale Vaadin.Will = YES -->] // end::stop
Rules that use
scope: raw (e.g.,
Vaadin.SourceCode) can’t be suppressed with these comments.