Vale documentation tests

Vale is a grammar, style, and word usage linter for the English language. Vale's configuration is stored in the .vale.ini file located in the root directory of projects. For example, the .vale.ini of the gitlab project.

Vale supports creating custom rules that extend any of several types of checks, which we store in the documentation directory of projects. For example, the doc/.vale directory of the gitlab project.

This configuration is also used in build pipelines, where error-level rules are enforced.

You can use Vale:

• On the command line.
• In a code editor.
• In a Git hook. Vale only reports errors in the Git hook (the same configuration as the CI/CD pipelines), and does not report suggestions or warnings.

Install Vale

Install vale using either:

• mise. For example:

  shellCopy

  mise use -g vale
  

• A package manager:

  • macOS using brew, run: brew install vale.
  • Linux, use your distribution's package manager or a released binary.

Configure Vale in your editor

Using linters in your editor is more convenient than having to run the commands from the command line.

To configure Vale in your editor, install one of the following as appropriate:

• Visual Studio Code ChrisChinchilla.vale-vscode extension. You can configure the plugin to display only a subset of alerts.

• Sublime Text SublimeLinter-vale package. To have Vale suggestions appears as blue instead of red (which is how errors appear), add vale configuration to your SublimeLinter configuration:

  jsonCopy

  "vale": {
    "styles": [{
      "mark_style": "outline",
      "scope": "region.bluish",
      "types": ["suggestion"]
    }]
  }
  

• LSP for Sublime Text package LSP-vale-ls.

• Vim ALE plugin.

• JetBrains plugin.

• Emacs Flycheck extension. A minimal configuration for Flycheck to work with Vale could look like:

  lispCopy

  (flycheck-define-checker vale
    "A checker for prose"
    :command ("vale" "--output" "line" "--no-wrap"
              source)
    :standard-input nil
    :error-patterns
      ((error line-start (file-name) ":" line ":" column ":" (id (one-or-more (not (any ":")))) ":" (message)   line-end))
    :modes (markdown-mode org-mode text-mode)
    :next-checkers ((t . markdown-markdownlint-cli))
  )
  
  (add-to-list 'flycheck-checkers 'vale)
  

  In this setup the markdownlint checker is set as a "next" checker from the defined vale checker. Enabling this custom Vale checker provides error linting from both Vale and markdownlint.

Result types

Vale returns three types of results:

• Error - For branding guidelines, trademark guidelines, and anything that causes content on the documentation site to render incorrectly.
• Warning - For general style guide rules, tenets, and best practices.
• Suggestion - For technical writing style preferences that may require refactoring of documentation or updates to an exceptions list.

The result types have these attributes:

When to add a new Vale rule

It's tempting to add a Vale rule for every style guide rule. However, we should be mindful of the effort to create and enforce a Vale rule, and the noise it creates.

In general, follow these guidelines:

• If you add an error-level Vale rule, you must fix the existing occurrences of the issue in the documentation before you can add the rule.

  If there are too many issues to fix in a single merge request, add the rule at a warning level. Then, fix the existing issues in follow-up merge requests. When the issues are fixed, promote the rule to an error.

• If you add a warning-level or suggestion-level rule, consider:

  • How many more warnings or suggestions it creates in the Vale output. If the number of additional warnings is significant, the rule might be too broad.

  • How often an author might ignore it because it's acceptable in the context. If the rule is too subjective, it cannot be adequately enforced and creates unnecessary additional warnings.

  • Whether it's appropriate to display in the merge request diff in the GitLab UI. If the rule is difficult to implement directly in the merge request (for example, it requires page refactoring), set it to suggestion-level so it displays in local editors only.

Where to add a new Vale rule

New Vale rules belong in one of two categories (known in Vale as styles). These rules are stored separately in specific styles directories specified in a project's .vale.ini file. For example, .vale.ini for the gitlab project.

Where to add your new rules depends on the type of rule you're proposing:

• gitlab_base: base rules that are applicable to any GitLab documentation.
• gitlab_docs: rules that are only applicable to documentation that is published to https://docs.gitlab.com.

Most new rules belong in gitlab_base.

Limit which tests are run

You can set Visual Studio Code to display only a subset of Vale alerts when viewing files:

1. Go to Preferences > Settings > Extensions > Vale.
2. In Vale CLI: Min Alert Level, select the minimum alert level you want displayed in files.

To display only a subset of Vale alerts when running Vale from the command line, use the --minAlertLevel flag, which accepts error, warning, or suggestion. Combine it with --config to point to the configuration file in the project, if needed:

vale --config .vale.ini --minAlertLevel error doc/**/*.md

Omit the flag to display all alerts, including suggestion level alerts.

Test one rule at a time

To test only a single rule when running Vale from the command line, modify this command, replacing OutdatedVersions with the name of the rule:

vale --no-wrap --filter='.Name=="gitlab_base.OutdatedVersions"' doc/**/*.md

Disable Vale tests

You can disable a specific Vale linting rule or all Vale linting rules for any portion of a document:

• To disable a specific rule, add a <!-- vale gitlab_<type>.rulename = NO --> tag before the text, and a <!-- vale gitlab_<type>.rulename = YES --> tag after the text, replacing rulename with the filename of a test in the directory of one of the GitLab styles.
• To disable all Vale linting rules, add a <!-- vale off --> tag before the text, and a <!-- vale on --> tag after the text.

Whenever possible, exclude only the problematic rule and lines.

For more information on Vale scoping rules, see Vale's documentation.

Workaround to disable Vale rules that use the raw scope

In general, you cannot disable Vale rules with the raw scope.

However, if a change causes Vale to fail because of a false positive, you can sometimes circumvent the by tweaking the formatting around the change. For example, sometimes you can add some extra spaces to the start of the line with the false positive. Be sure to test that the page continues to render fine, and add an HTML comment describing the reason for the special formatting.

For instance (taken from a real example):

<!--
The following codeblock uses extra spaces to avoid the Vale ReferenceLinks test.
Do not remove the two-space nesting.
-->

  - [Use a reference-style link that's normally prohibited][1]

  [1]: https://example.com/

For more information, see this Vale issue.

Show Vale warnings on commit or push

By default, the Vale check in Lefthook only shows error-level issues. The default branches have no Vale errors, so any errors listed here are introduced by the commit to the branch.

To also see the Vale warnings, set a local environment variable: VALE_WARNINGS=true.

Enable Vale warnings on commit or push to improve the documentation suite by:

• Detecting warnings you might be introducing with your commits.
• Identifying warnings that already exist in the page, which you can resolve to reduce technical debt.

These warnings:

• Don't stop the commit from working.
• Don't result in a broken pipeline.
• Include all warnings for a file, not just warnings that are introduced by the commits.

To enable Vale warnings with Lefthook:

• Automatically, add VALE_WARNINGS=true to your shell configuration.

• Manually, prepend VALE_WARNINGS=true to invocations of lefthook. For example:

  shellCopy

  VALE_WARNINGS=true bundle exec lefthook run pre-commit
  

You can also configure your editor to show Vale warnings.

Resolve problems Vale identifies

Spelling test

When Vale flags a valid word as a spelling mistake, you can fix it following these guidelines:

Uppercase (acronym) test

The Uppercase.yml test checks for incorrect usage of words in all capitals. For example, avoid usage like This is NOT important.

If the word must be in all capitals, follow these guidelines:

Readability score

In ReadingLevel.yml, we have implemented the Flesch-Kincaid grade level test to determine the readability of our documentation.

As a general guideline, the lower the score, the more readable the documentation. For example, a page that scores 12 before a set of changes, and 9 after, indicates an iterative improvement to readability. The score is not an exact science, but is meant to help indicate the general complexity level of the page.

The readability score is calculated based on the number of words per sentence, and the number of syllables per word. For more information, see the Vale documentation.

Export Vale results to a file

To export all (or filtered) Vale results to a file, modify this command:

# Returns results of types suggestion, warning, and error
find . -name '*.md' | sort | xargs vale --minAlertLevel suggestion --output line > ../../results.txt

# Returns only warnings and errors
find . -name '*.md' | sort | xargs vale --minAlertLevel warning --output line > ../../results.txt

# Returns only errors
find . -name '*.md' | sort | xargs vale --minAlertLevel error --output line > ../../results.txt

These results can be used to generate documentation-related issues for Hackathons.

Enable custom rules locally

Vale 3.0 and later supports using two locations for rules. This change enables you to create and use your own custom rules alongside the rules included in a project.

To create and use custom rules locally on macOS:

1. Create a local file in the Application Support folder for Vale:

   shellCopy

   touch ~/Library/Application\ Support/vale/.vale.ini
   

2. Add these lines to the .vale.ini file you just created:

   yamlCopy

   [*.md]
   BasedOnStyles = local
   

3. If the folder ~/Library/Application Support/vale/styles/local does not exist, create it:

   shellCopy

   mkdir ~/Library/Application\ Support/vale/styles/local
   

4. Add your desired rules to ~/Library/Application Support/vale/styles/local.

Rules in your local style directory are prefixed with local instead of gitlab in Vale results, like this:

$ vale --minAlertLevel warning doc/ci/yaml/index.md

 doc/ci/yaml/index.md
    ...[snip]...
 3876:17   warning  Instead of future tense 'will   gitlab.FutureTense
                    be', use present tense.
 3897:26   error    Remove 'documentation'          local.new-rule

✖ 1 error, 5 warnings and 0 suggestions in 1 file.

Related topics

• Styles in Vale
• Example styles containing rules you can adapt