Vale at Red Hat

Get started with linting Red Hat documentation with Vale and the Red Hat Style for Vale.

Requirements

The RedHat Style for Vale style requires Vale version 3.7 or above.

Red Hat style for Vale

The RedHat style for Vale includes language rules designed for Open Source documentation and is mandatory for Red Hat products. The Red Hat language rules originate from:

Red Hat supplementary style guide for product documentation
Latest edition of the IBM Style Guide (W3id login required)
Vale-compatible implementation of IBM Developer Editorial Style Guide
Custom Vale open-source dictionary for American English

Important

The RedHat style for Vale requires Vale version 3.7 and above.

Vale v3 introduced a breaking change for the Vale vocabulary folder location. For Vale v3+, if you use a vocabulary with your project, ensure that the vocabulary folder matches this folder structure:

.vale/styles/config/vocabularies/<project_vocab_folder>

For more information see, Vocabularies.

Additional resources

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

Important

These rules are suitable for AsciiDoc source files only.

To use the AsciiDoc style, do the following:

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

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

Open a shell prompt and change to the project directory:
```
$ cd <project_dir>
```

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

OpenShift AsciiDoc style for Vale

The OpenShiftAsciiDoc style for Vale consists of rules suitable for OpenShift documentation projects written in AsciiDoc. It lints common OpenShift AsciiDoc syntax errors as outlined in OpenShift documentation guidelines Use the OpenShiftAsciiDoc style in conjunction with other Vale styles.

Some of the errors that the OpenShiftAsciiDoc rules highlight include:

:_additional-resources: role attribute declaration
Terminal code block missing a shell prompt symbol ($) at the beginning of the line
Missing .Example output title for example listing blocks
ID missing the {_context} variable at the end of the ID
modules missing the :_mod-docs-content-type: variable
Cross references (xref) missing anchor IDs
Cross references that use .adoc instead of .html for links
Cross references missing link alt text

Important

These rules are suitable for AsciiDoc source files only.

To use the OpenShiftAsciiDoc style, do the following:

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

Example .vale.ini

StylesPath = .vale/styles

MinAlertLevel = suggestion

Packages = RedHat, OpenShiftAsciiDoc

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

Note

Some rules are applicable to modules only. To use a different set of rules for modules and assemblies, create two .vale.ini files, one in the project root, and one in the /modules folder. For the root .vale.ini file, add the following to disable rules that don’t apply to assemblies:

# Disable module specific rules
OpenShiftAsciiDoc.ModuleContainsParentAssemblyComment = NO
OpenShiftAsciiDoc.NoNestingInModules = NO
OpenShiftAsciiDoc.NoXrefInModules = NO

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

Open a shell prompt and change to the project directory:
```
$ cd <project_dir>
```

Run the sync command to pull the new Rule packages

$ vale sync

Example output

 SUCCESS  Downloaded package 'RedHat'
 SUCCESS  Downloaded package 'OpenShiftAsciiDoc'
Downloading packages [2/2] ██████████████████ 100% | 3s

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

.vale/styles/OpenShiftAsciiDoc

Additional resources