Automatic checks

The starter pack comes with several automatic checks that you can (and should!) run on your documentation before committing and pushing changes.

The following checks are available:

• Accessibility check
• Inclusive language check
• Link check
• Lint check
• Spelling check
• Style guide linting

Install prerequisite software

Some of the tools used by the automatic checks require npm. Install npm using the appropriate method for your operating system through one of the following methods:

• Your preferred package manager

• By following the node version manager installation process

• For Debian and Ubuntu Linux distributions, the sudo apt install npm command

To install the validation tools:

make pa11y-install
make pymarkdownlnt-install  # if using Markdown

Note

pa11y is a non-blocking check in our current documentation workflow.

Default GitHub actions

The documentation-checks.yaml workflow comes from the documentation-workflows repository and supports the following inputs.

Input	Description	Default
working-directory	The root of the documentation project. This input is required.	None
python-version	The Python interpreter to use for the workflow’s jobs.	'3.10'
'fetch-depth'	The number of commits to fetch from your repository.	The full history is fetched.
runs-on	The host system for the workflow’s runners.	'["ubuntu-24.04"]'
makefile	The Makefile that checks are invoked from.	'Makefile'
install-target	The make target for installing required tools.	'install'
spelling-target	The make target to run for the spelling check.	'spelling'
woke-target	The make target to run for the inclusive language check	'woke'
linkcheck-target	The make target to run for the link check.	'linkcheck'

The current defaults force usage of Canonical-hosted runners, which some projects may not be able to use. You may select your own runners by providing a runs-on value, as shown by line 6 in the following example:

jobs:
 documentation-checks:
   uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main
   with:
     working-directory: "docs"
     runs-on: "ubuntu-22.04"

Workflow triggers

For efficiency, the documentation check workflows are configured to run only when changes are made to files in the docs/ directory. If your project is structured differently, or if you want to run the checks on other directories, modify the trigger paths in the workflow files:

on:
  pull_request:
    paths:
      - 'docs/**'   # Only run on changes to the docs directory