An essential part of the documentation is being consistent. You must be consistent with how you write and present your documents and the information in them.

This includes both the written content and the code blocks. Your documentation should follow a style guide that keeps your content across pages consistent.

However, ensuring that your content follows the style guide manually is difficult. You might easily miss small mistakes here and there. This is especially the case when your documentation is open source, where contributors can make fixes or changes to it.

This article covers the different methods and ways you can lint prose or content and code blocks to ensure it follows your style guide.

Why Use a Style Guide?

Documentation should provide a great developer experience. This includes consistency, clarity, and technical accuracy.

Creating a style guide can provide your documentation with the following benefits:

  • Your tone remains consistent. For example, you shouldn't change between using "you" and "we". You should decide on the tone you want to speak to the developer with and stick to it.
  • You ensure your content is outlined the same across pages. If you use dividers between sections, you should do that across the documentation. Switching between using and not using them can confuse the reader on when a section starts and ends.
  • You maintain content that is written for everyone. Your tone shouldn't be biased toward gender, development level, disabilities, or anything similar.

Although style guides generally refer to the content of the documentation, you should also maintain a set of rules for your code block.

For example, if you're using JavaScript make sure you either use or don't use semicolons consistently. Similarly, make sure you either use double quotes across the code blocks or single quotes.

Markdown Content

Most documentation is written in Markdown (MD) or MDX formats. So, this article specifically targets linting markdown files.

If you write your documentation in different file formats, these solutions might not work for you.

Lint Prose with Vale

Vale is a linter for prose or content. It allows you to define rules based on your style guide, then shows you errors, warnings, or suggestions for changes in your documentation.

So many projects and companies use Vale, including GitHub, Microsoft, Angular, and more.

Vale provides some ready-made styles and packages that you can immediately add to your configurations. For example, you can use Microsoft's style guide.

Vale also provides ready-made style guides based on the purpose of your documentation. For example, if your documentation includes job listings, you can use the Joblint styles.

Vale is easy to set up and use. You can then either choose from existing styles or create your own. Vale also provides a config generator to save you time.

Then, you can test your content by simply running a command like this:

vale README.md

Vale also has a VS Code extension that allows you to quickly catch errors and warnings in your editor.

Not only can you use Vale through the command line, but you can also integrate Vale into your development or release pipeline.

For example, Vale provides a GitHub Action that you can use to test whether a PR has any lint errors. You can then ensure that no errors are merged into your repositories by mistake.

Lint Code with ESLint

ESLint is a linter that allows you to identify problems in JavaScript code. It also allows you to enforce style rules in your code to ensure that everything is consistent.

There are plugins that allow running ESLint with other languages. For example, typescript-eslint allows linting TypeScript.

By default, ESLint wouldn't work for lining code in the documentation. The problem is that the linter has to recognize where code blocks are within the markdown file, recognize the language of the code block, then check if there are any errors in it.

To do that with ESLint, you'll need to use the eslint-plugin-markdown. This plugin allows you to lint JavaScript, TypeScript, and other languages within your documentation files.

You can then define the rules similar to how you would with ESLint.

You can install the plugin in your Node.js project with the following command:

npm install --save-dev eslint eslint-plugin-markdown

Then, create the file .eslintrc.js in the root directory with the following content:

module.exports = {
    extends: "plugin:markdown/recommended",
    plugins: ["markdown"],
    overrides: [
        {
            files: ["**/*.md"],
            processor: "markdown/markdown"
        },
    ]
};

This enables running the linter on Markdown files. You can also add **/*.mdx to the files array to run the linter on MDX files as well.

You can specify which languages you want to lint in the overrides array. For example:

overrides: [
    //...
    {
    	files: ["**/*.md/*.js"],
        // optional
        rules: {
			// ...
        }
    }
]

All languages are nested under **/*.md. So, to specify JavaScript files, you pass the pattern **/*.md/*.js.

You can also optionally pass rules specific to that language under the rules property.

Then, you can run the eslint command to test the code blocks in your documentation:

eslint

This assumes that you created the configuration file at the root of your project. Otherwise, you need to pass the CLI tool some options.

You can also pass it the --fix option to immediately fix errors that can be fixed:

eslint --fix

You can also run ESLint when pull requests are sent into your repository by creating a GitHub Action that runs the above command. This ensures that all contributions to your project don't lead to errors in your documentation.

Conclusion

This article lists two tools that can be used for configuring and automating linters both for the prose and the code of your documentation.

Although these tools are widely used, there are other tools that can be used for different types of documentation formats or projects. Regardless of what tool you use, invest in automating this process as it ensures clear documentation for developers.