Linting Your Documentation

Altis support checking your documentation files for formatting and syntax errors. It can also run a style and spelling check on your documentation.

The formatting and syntax checks will highlight any issues that may affect how your documentation will appear in the WordPress dashboard under the Documentation tab.

Commands

The commands to run are as follows:

composer dev-tools lintdocs files --lint-path=path-to-module files|markdown|style|all

Where:

  • lint-path is the path to the module to test relative to the root of your project,
  • files will check the required file (README.md) exists in your docs folder and that you do not have a markdown file with the same name as its containing folder,
  • markdown will check the Markdown syntax and formatting of each of your files, and
  • style will run a style and spell check on your files.

If you specify all it will run all the above checks.

The command expects the documentation files to be in sub-folders of the module path you specify. It will check folders called docs, user-docs, and other-docs. If none of them exist, it will handle that.

Configuration

To initialise the configuration you need to run the command

composer dev-tools bootstrap lintdocs

This will place files called .markdownlint.yml and .vale.ini and a folder called styles in the root directory of your project.

Markdown Lint

The markdown sub-command runs markdownlint on all your markdown files. Documentation about the tool can be found on GitHub

The configuration file for the tool is .markdownlint.yml. You can find the details of the rules it configures in the online help. The file is commented, and you can adjust it to suite your own preferences. Altis recommends you leave most of the rules as default.

Vale Style checker

The Vale style checker is an open-source tool that allows you to enforce editorial style guides. It comes with several off-the shelf style guides and you can add or write your own. Altis uses the proselint style and adds an Altis specific spell check dictionary.

The styles folder contains the style rules for the Vale style checker. The configuration file vale.ini specifies which styles set to use.

You will find documentation on the structure of the Styles and how to write your own, in the online documentation.

Files checker

The files check does not have any configuration but will check the two main requirements for Altis' built-in documentation.

  1. There should be a README.md file in each folder and sub-folder.
  2. There should not be a file with the same base name as its parent folder.