Repository files navigation

This repository provides GitHub's recommendedmarkdownlint configurations, and additional rules for use on GitHub open source and internal projects.

In addition to defaults defined bymarkdownlint, we use this repository to enforce rules not defined by default, including our own custom rules.

See opinions codified inindex.js.

The following are custom rules defined in this plugin.

• GH001no-default-alt-text
• GH002no-generic-link-text
• GH003no-empty-alt-text

Seemarkdownlint rules for documentation on rules pulled in frommarkdownlint.

Important: We support the use ofmarkdownlint throughmarkdownlint-cli2 instead ofmarkdownlint-cli for compatibility with thevscode-markdownlint plugin.

1. Create a.markdownlint-cli2.mjs file in the root of your repository.

   touch .markdownlint-cli2.mjs

2. Install packages.

   npm install -D markdownlint-cli2# if updating existing package, check for updatesnpm install -D @github/markdownlint-github [--@github:registry=https://registry.npmjs.org]npm install -D markdownlint-cli2-formatter-pretty

3. Add/modify your linting script inpackage.json.

   "scripts": {"lint:markdown":"markdownlint-cli2\"**/*.{md,mdx}\"\"!node_modules\""}

4. Edit.markdownlint-cli2.mjs file to suit your needs. Start with

   importconfigOptions,{init}from"@github/markdownlint-github"constoptions={config:init(),customRules:["@github/markdownlint-github"],outputFormatters:[["markdownlint-cli2-formatter-pretty",{"appendLink":true}]// ensures the error message includes a link to the rule documentation]}exportdefaultoptions

   Or, you can also pass in configuration options that you wish to override the default. Read more atCustomizing configurations.This looks like:

   importconfigOptions,{init}from"@github/markdownlint-github"constoverriddenOptions=init({'fenced-code-language':false,// Custom overrides})constoptions={config:overriddenOptions,customRules:["@github/markdownlint-github"],outputFormatters:[["markdownlint-cli2-formatter-pretty",{"appendLink":true}]]}exportdefaultoptions

5. Install thevscode-markdownlint plugin to ensuremarkdownlint violations are surfaced in the file. This plugin should flag rules based off your.markdownlint-cli2.mjs configuration. When you make edits to your configuration, you will need to reload the VSCode window (Ctrl+Shift+P ->Reload Window) to ensure the extension syncs. If your project runs on Codespaces, consider adding this extension to your.devcontainer/devcontainer.json so that this extension is installed to new Codespaces by default.

You may determine that the defaults set by this plugin are not suitable for your project.

This plugin will pull in the the defaults defined bymarkdownlint, several of which pertain to stylistic practices. You may choose to disable these rules if you determine it doesn't provide value for your project.

However, others of these rules shouldNOT be disabled because they encourage best accessibility practices. Disabling these rules will negatively impact accessibility. These rules are defined inaccessibility.json.

To review configurations supported bymarkdownlint, seemarkdownlint-cli2 configuration.

You may write custom rules within your repository. Follow thecustom rules guide inmarkdownlint to write your rule.

The rule will need to be enabled in the configuration. For instance, if you introducesome-rule.js with the name "some-rule", you must set the path of the custom rule in the.markdownlint-cli2.mjs file:

importconfigOptions,{init}from"@github/markdownlint-github"constoptions=init({"some-rule":true,customRules:["@github/markdownlint-github","some-rule.js"],})exportdefaultoptions

Seemarkdownlint-cli2 configuration.

Consider upstreaming any rules you find useful as proposals to this repository.

This project is licensed under the terms of the MIT open source license. Pleaserefer tothe MIT license for the full terms.

SeeCODEOWNERS.

Please readContributing Guide for more information.