Documentation/Tools/Linting

This page describes how to use documentation linting tools to check technical documentation and get suggestions for how to improve the prose.

Quick start

To start using the linting tools, go to:

About documentation linting tools

Three documentation linting tools are available:

  • local linter - a command line tool and a linter you can use in your code editor, with a rule configuration ready for linting documentation in Wikimedia movement projects
  • GitLab CI pipeline template - ready to lint documentation stored in code comments or documentation files in a code repository
  • wiki page linter - a web-based tool capable of linting wiki pages

These tools rely on the same linting rules and use the same open-source application - Vale - to lint documentation. This guarantees that all documentation follows the same style guidelines.

For a full reference of linting rules, see Linter rule reference.

Security

Documentation linting tools are designed for linting technical documentation that's either publicly available, or will be publicly available soon. These tools didn't undergo a security review. While they're built on top of trustworthy, open-source applications and libraries, they might not be suitable for linting private or confidential content.

Background

These tools were developed in March-May 2025. For project background information, see task T388109 in Phabricator.

How to use

Linting documentation locally

Use the local linter to lint the following on your device:

  • Markdown and reStructuredText documentation files
  • documentation in HTML and plain text files
  • documentation in code comments

To lint locally, you must install the linter on your device and place the configuration files in the appropriate directory. See How to use Vale to lint documentation in your text editor for details.

Linting documentation in a CI pipeline

Use the GitLab CI pipeline to lint documentation stored in a GitLab repository. For example, you can configure the pipeline to run the linting step when publishing docs or building your application. The pipeline supports the same documentation formats as the local linter.

To use the GitLab CI pipeline, you must add the CI configuration and the linter configuration to your repository. See How to use Vale in a GitLab CI pipeline for details.

Linting documentation pages on wiki

Use the documentation linter for wikis to lint documentation published on mediawiki.org or Wikitech. This linter is available as a tool on Toolforge and doesn't require any installation or configuration.

You can find the usage instructions on the tool's landing page.

Linting good practices

The best way to lint documentation in your project depends on a few factors, such as documentation format and size, and the number of documentation contributors. This section contains tips on how to lint docs depending on these factors.

Documentation on mediawiki.org or Wikitech

The only tool available for linting on-wiki documentation is the documentation linter for wikis. It allows you to lint one page at a time and has no automation features. It's most effective when used consistently by all documentation contributors.

Additionally, you can install the linter locally to lint your notes before you convert them to the final, on-wiki format. This makes the process of writing and editing your docs a bit longer, but minimizes the number of changes you'll need to make after publishing.

Finally, if you aren't sure which documentation to look into first and your documentation is on mediawiki.org, you can use the documentation metrics tool to help you pick documentation that requires work.

Documentation stored in a repository

You can use the GitLab CI pipeline and the local linter to lint content stored in a repository. If you have a lot of documentation in the repository, it's best to introduce linting gradually.

Get an overview of your documentation

Use the local linter to get an overview of the documentation status. Enable the local linter on your device as described in How to use Vale to lint documentation in your text editor or IDE. Then, use the vale command to lint all the available files containing documentation and analyze the results.

Choose the linting strategy

When you run the linter for the first time in a repository with lots of documentation, you'll probably get many warnings and suggestions. You need to consider which types of messages are helpful for your documentation. It's up to you and the team maintaining the documentation to decide how to proceed:

  • You can choose to organize a documentation sprint or a documentation-focused hackathon, and fix the warnings or apply suggestions as soon as possible.
  • You can choose to disable some rules in GitLab CI but keep them in the local linter configuration to encourage fixes during regular development and prevent the introduction of new warnings. For example, you may see a lot of passive voice warnings and decide to disable them in CI. Note that if you choose to do that, you'll need two separate linter configuration files for local and CI linting as described in How to use separate configurations for linting locally and in CI.
  • You can choose to disable some rules everywhere (both locally and in GitLab CI) if you don't think they're important to the quality of your documentation.

Commit the linter configuration to project repository

Once you've decided how to handle different types of rules, commit the linter configuration to your project's repository. It's also a good idea to share your linting strategy with other maintainers by creating a wiki page or sending an announcement.

How to get help

Technical documentation linting tools are maintained by the Wikimedia Technical Documentation Team. You can reach us using any method described on our team page. You can also join us in the #wikimedia-techdocs connect channel on libera.chat.

How to contribute

Documentation linting tools are experimental and aren't intended to serve as the production solution in the long term. We're treating them as a stepping stone towards more reliable tooling. At this stage, the best way to contribute is to use these tools in your projects, report problems, errors, and design flaws on the Documentation talk page, and help us figure out the solutions.