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

These rules are suitable for AsciiDoc source files only.

To use the OpenShiftAsciiDoc style, do the following:

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

    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

  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 '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