Docs

Documentation versions (currently viewingVaadin 24)

Vale

Vale helps contributors to follow the writing style rules and guidelines that are specific to the Vaadin and Hilla documentation.

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.

The lint/vale check in a GitHub pull request.
lint/vale PR Check

If the Vale check fails — that is if it produces errors, warnings, or suggestions — you can see those in the Files changed tab.

GitHub pull request tabs, with the Files changed tab active.
Files Changed Tab

An annotation shows below the line where Vale detected an issue.

A warning and a suggestion reported by Vale on two lines of a file changed in a pull request.
Vale PR Annotation Examples

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:

// 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.