AsciiDoc style for Vale

The AsciiDoc style for Vale consists of rules suitable for documentation projects written in AsciiDoc. It lints common AsciiDoc syntax errors. Use the AsciiDoc style in conjunction with other Vale styles. Many of the AsciiDoc rules replicate features of the Visual Studio Code editor Asciidoctor plugin.

Some of the errors that the AsciiDoc rules highlight include:

  • Open attribute blocks

  • Open quoted ID values

  • Images and links that are missing accessibility alt tags

  • Missing or incorrect callouts

  • Unterminated admonition, listing, and table blocks

  • Unbalanced if statements

These rules are suitable for AsciiDoc source files only.

To use the AsciiDoc style, do the following:

  1. Update your project .vale.ini to include the the AsciiDoc style. Add Asciidoc to the Packages and BasedOnStyles fields. For example:

    Example .vale.ini
    StylesPath = .vale/styles

MinAlertLevel = suggestion

Packages = RedHat, AsciiDoc

# Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files
[[!.]*.adoc]
BasedOnStyles = RedHat, AsciiDoc

  2. Sync your project that contains the updated .vale.ini configuration, for example:

    1. Open a shell prompt and change to the project directory:

      $ cd <project_dir>

    2. Run the sync command to pull the new Rule packages

      $ vale sync
      Example output
       SUCCESS  Downloaded package 'RedHat'
 SUCCESS  Downloaded package 'AsciiDoc'
Downloading packages [2/2] ██████████████████ 100% | 3s

The Vale at Red Hat repository contains the AsciiDoc style in the following directory:

.vale/styles/AsciiDoc
Additional resources