About the GitHub Docs content linter
Our content linter enforces style guide rules in our Markdown content.
The linter uses markdownlint as the framework to perform checks, report flaws, and automatically fix content, when possible. This framework flexibly runs specific rules, gives descriptive error messages, and fixes errors. The GitHub Docs content linter uses several existing markdownlint rules and additional custom rules to check the Markdown content in our content and data directories. Our custom rules implement checks that are either not yet available in the markdownlint framework or are specific to GitHub Docs content. Rules check the syntax for both Markdown and Liquid.
Running the GitHub Docs content linter
The GitHub Docs content linter will run automatically on pre-commit, but you can also run it manually.
Automatically run the linter on pre-commit
When you are writing content locally and committing files using the command line, those staged files will automatically be linted by the content linter. Both warnings and errors are reported, but only errors will prevent your commit from completing.
If any errors are reported, your commit will not complete. You will need to fix the reported errors, re-add the changed files, and commit your changes again. Any errors that are reported must be fixed to prevent introducing errors in the content that are in violation of the GitHub Docs style guide. If any warnings are reported, you can optionally choose to fix them or not.
When you are writing content locally, there are several rules that you can fix automatically using the command line. If you want to automatically fix errors that can be fixed, see Automatically fix errors that can be fixed.
If you are editing a file in the GitHub UI, you will not be able to automatically fix errors or run the linter on a commit, but you will get a CI failure if the content violates any rules with a severity of error.
Manually run the linter
Run the linter on staged and changed files
Use the following command to run the linter locally on your staged and changed files. It will output both warning and error severity flaws.
npm run lint-content
Run the linter on staged and changed files and only report errors
Use the following command to run the linter locally on your staged and changed files, and report only error severity flaws.
npm run lint-content -- --errors