Using the content linter - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Using the content linter You can use content linter to check your contributions for errors. In this article 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 Run the linter on specific files or directories Use the following command to run the linter locally on specific files or directories.
Separate multiple paths with a space. You can include both files and directories in the same command. npm run lint-content -- \ --paths content/FILENAME.md content/DIRECTORY Automatically fix errors that can be fixed If an error has fixable: true in its description, you can use the following commands to automatically fix them. Run this command to fix staged and changed files only: npm run lint-content -- --fix Run this command to fix specific files or directories: npm run lint-content -- \ --fix --paths content/FILENAME.md content/DIRECTORY Run a specific set of linter rules Use the following command to run one or more specific linter rules.
These examples run the heading-increment and code-fence-line-length rules. Replace heading-increment code-fence-line-length with one or more linter aliases that you would like to run. To see the list of linter rules you can pass to this option, run npm run lint-content -- --help . You can use either the short name (for example, MD001 ) or long name (for example, heading-increment ) of a linter rule. Run the specified linter rules on all staged and changed files: npm run lint-content -- \ --rules heading-increment code-fence-line-length Run the specified linter rules on specific files or directories: npm run lint-content -- \ --rules heading-increment code-fence-line-length \ --path content/FILENAME.md content/DIRECTORY Bypass the commit hook If the linter catches errors that you did not introduce, you can bypass the git commit hook by using the --no-verify option when you commit your changes. git commit -m 'MESSAGE' --no-verify Display the help menu for the content linter script npm run lint-content -- --help Linting rules Each rule is configured in a file in src/content-linter/style , which is where the severities of rules are defined.
Errors must be addressed before merging your changes to the main branch. Warnings should be addressed but do not prevent a change from being merged into the main branch. Most rules will eventually be promoted to errors, once the content no longer has warning violations. Rule ID Rule Name(s) Description Severity Tags MD001 heading-increment Heading levels should only increment by one level at a time error headings MD011 no-reversed-links Reversed link syntax error links MD014 commands-show-output Dollar signs used before commands without showing output error code MD018 no-missing-space-atx No space after hash on atx style heading error headings, atx, spaces MD019 no-multiple-space-atx Multiple spaces after hash on atx style heading error headings, atx, spaces MD023 heading-start-left Headings must start at the beginning of the line error headings, spaces MD027 no-multiple-space-blockquote Multiple spaces after blockquote symbol error blockquote, whitespace, indentation MD029 ol-prefix Ordered list item prefix error ol MD030 list-marker-space Spaces after list markers error ol, ul, whitespace MD031 blanks-around-fences Fenced code blocks should be surrounded by blank lines error code, blank_lines MD037 no-space-in-emphasis Spaces inside emphasis markers error whitespace, emphasis MD039 no-space-in-links Spaces inside link text error whitespace, links MD040 fenced-code-language Fenced code blocks should have a language specified error code, language MD042 no-empty-links No empty links error links MD050 strong-style Strong style error emphasis GH001 no-default-alt-text Images should have meaningful alternative text (alt text) error accessibility, images GH002 no-generic-link-text Avoid using generic link text like Learn more or Click here error accessibility, links GHD001 link-punctuation Internal link titles must not contain punctuation error links, url GHD002 internal-links-no-lang Internal links must not have a hardcoded language code error links, url GHD003 internal-links-slash Internal links must start with a / error links, url GHD004 image-file-kebab-case Image file names must use kebab-case error images GHD005 hardcoded-data-variable Strings that contain "personal access token" should use the product variable instead error single-source GHD006 internal-links-old-version Internal links must not have a hardcoded version using old versioning syntax error links, url, versioning GHD007 code-annotations Code annotations defined in Markdown must contain a specific layout frontmatter property error code, feature, annotate, frontmatter GHD008 early-access-references Files that are not early access should not reference early-access or early-access files error feature, early-access GHD009 frontmatter-early-access-references Files that are not early access should not have frontmatter that references early-access error frontmatter, feature, early-access GHD010 frontmatter-hidden-docs Articles with frontmatter property hidden can only be located in specific products error frontmatter, feature, early-access GHD012 frontmatter-schema Frontmatter must conform to the schema error frontmatter, schema GHD013 github-owned-action-references GitHub-owned action references should not be hardcoded error feature, actions GHD014 liquid-data-references-defined Liquid data or indented data references were found in content that have no value or do not exist in the data directory error liquid GHD015 liquid-data-tag-format Liquid data or indented data referen
The rest of this page is on the live site.