github/markdownlint-github

An opinionated collection of markdownlint rules used by GitHub.

Markdownlint-github

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

Opinions

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

See opinions codified in index.js.

Rules

The following are custom rules defined in this plugin.

• GH001 no-default-alt-text
• GH002 no-generic-link-text
• GH003 no-empty-alt-text

See markdownlint rules for documentation on rules pulled in from markdownlint.

Usage

Important: We support the use of markdownlint through markdownlint-cli2 instead of markdownlint-cli for compatibility with the vscode-markdownlint plugin.

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

   touch .markdownlint-cli2.cjs

2. Install packages.

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

3. Add/modify your linting script in package.json.

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

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

   const options = require('@github/markdownlint-github').init()
   module.exports = {
       config: options,
       customRules: ["@github/markdownlint-github"],
       outputFormatters: [
         [ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ] // ensures the error message includes a link to the rule documentation
       ]
   }

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

   const options = require('@github/markdownlint-github').init({
       'fenced-code-language': false, // Custom overrides
   })
   module.exports = {
       config: options,
       customRules: ["@github/markdownlint-github"],
       outputFormatters: [
         [ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ]
       ]
   }

5. Install the vscode-markdownlint plugin to ensure markdownlint violations are surfaced in the file. This plugin should flag rules based off your .markdownlint-cli2.cjs 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.

Customizing configurations

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 by markdownlint, 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 should NOT be disabled because they encourage best accessibility practices. Disabling these rules will negatively impact accessibility. These rules are defined in accessibility.json.

To review configurations supported by markdownlint, see markdownlint-cli2 configuration.

Advanced: Adding custom rules in your codebase

You may write custom rules within your repository. Follow the custom rules guide in markdownlint to write your rule.

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

module.exports = require('@github/markdownlint-github').init({
    "some-rule": true,
    customRules: ["@github/markdownlint-github", "some-rule.js"],
})

See markdownlint-cli2 configuration.

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

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.

Maintainers

See CODEOWNERS.

Contributing

Please read Contributing Guide for more information.

markdownlint-github's Issues

Two new rules; are there more on the way?

Opening as a ticket since discussions are not enabled for this repo.

The only two rules this adds is GH001 No default alt text & GH002 No generic link text right? While all the rules from markdownlint are inherited?

Will this get more opinionated? I usually like to stick to @github's way of doing things on the platform. I know I can add my own of course.

"header" aliases have been removed in markdown-cli2

We recently updated markdownlint-cli2 on The Hub and noticed we started receiving increased errors related to headings. I dove into why and noticed that markdownlint-cli2 has removed the rule aliases that use the word "header" in favour of "heading".

As per the commit message, "header" aliases were deprecated in v0.9.0. I checked your package.json and saw you're depending in v0.13.0 but still have rules with the "header" alias.

These rules should be updated to use "heading" instead of "header".

Provide rationale for the rules enabled or disabled

I think it will be helpful to provide context on why we recommend these configurations.

In base.json

{
    "default": true,
    "no-inline-html": false,
    "no-bare-urls": false,
    "no-blanks-blockquote": false,
    "fenced-code-language": true
}

In accessibility.json

{
    "no-alt-text": true,
    "no-default-alt-text": true,
    "no-duplicate-header": true,
    "no-emphasis-as-header": true,
    "no-generic-link-text": true,
    "no-space-in-links": false,
    "ol-prefix": "ordered",
    "single-h1": true,
    "ul-style": true
}

Some of these are somewhat obvious, while others are less so.

Default error output does not include link to documentation

The default error message for markdown-cli2 does not include description, aka the optional URL that we pass into the URL to provide consumers with more context about the rule.

It looks like as though we'd need projects to configure a separate formatter like formatter-pretty if we want the error message to link to the description URL. I don't like that we need to install a separate dependency, but this is the more idiomatic route.

Another option is to just include the URL as part of the error message so the formatter doesn't need to be configured but this is less idiomatic.

Update guidance to recommend `markdowncli-2` and to use the VSCode extension

I think we will want to update the guidance in the README per @smockle revelation in https://github.com/github/accessibility/pull/1941 that the VSCode extension doesn't work with the current configuration recommendation.

We'll additionally want to include the config updates in https://github.com/github/accessibility/pull/2535.

Create a `max-heading-level` rule

When Markdown content is rendered on GitHub, it is rendered into the context of a webpage. This means there is already an external heading structure to contend with.

In issue and PR comments, the maximum heading level that should be used is 3 (###). In files in Code View, the maximum should be 2 (##).

I think it's debatable whether Markdown files should be written with their intended viewing location in mind - Markdown is supposed to be a rendering-agnostic markup format. But comments should probably always be written like this. So I think it would be useful to make a new rule available, but disable it by default.

I propose we make this generic, allowing the linter to customize the heading level for the situation. For example, the following configuration would be for comments on github.com:

{
    "max-heading-level": {
        "level": 3
    }
}

Related:

• iansan5653/github-markdown-a11y-extension#14

i18n support

Related: #10 (comment)

Investigate adding support for i18n. It would be worth seeing what markdownlint does.

Add docs for each rule

I think that each rule should be documented

Re-organize repo structure

As we add more files, I think it'll be beneficial to have a directory structure to place the rules and docs. Maybe something like:

src
--rules
----no-default-alt-text.js
----no-generic-link-text.js
----index.js
--helpers
test
--utils
------no-default-alt-text.test.js
------no-generic-link-text.test.js
docs
--rules
package.json
index.js
README.md

Make publish step more automated

Acceptance criteria

• Follow guidance to automatically publish on release
• Create workflow to automatically release on merge to main
• Update documentation to reflect new process

Document nuance around `no-duplicate-header` rule

This rule is set to true but I think there's some nuance around when this rule should be configured.

The rationale behind the no-duplicate-header rule is that some markdown parsers will generate anchor links from headings, and if the heading is the same, two headings in separate areas of the page will share the same anchor link. We see this issue in Primer docs.

However, on GitHub repos, the GitHub markdown parser ensures headings that share same text have unique IDs so the generated anchor links are unique even if the heading text is the same.

So I believe we wouldn't need to enforce that heading texts on a page are completely non-duplicated in other cases. I don't believe it's necessary to have completely unique heading text on a page for accessibility purposes. However, I believe there are accessibility benefits from enforcing that sibling headings are unique.

We could recommend setting siblings_only parameter which allows heading duplication for non-sibling headings and enforces sibling headings are unique.

Could we document these nuances?

Make repo public

I think this repo can be public.

Flag `image`, `Image` usage as alt text

Could we expand the no-default-alt-text rule? Not sure if image or Image is a default for anything but it shouldn't be used as alt text.