markdown

Global Markdownlint Configuration for GFM in VS Code

by

I’ve been working on a lot of documentation lately, and I’ve been trying to adhere to standards by linting my Markdown in VS Code the same way I lint my code. That being said, I’ve grown weary of fighting the linter over a few rules.

Note: These instructions assume you are using macOS.

Configure VS Code markdownlint with rules intended for GitHub Flavored Markdown (GFM). These settings provide sensible defaults for writing README files and other Markdown documentation hosted on GitHub.

Create the Configuration File

Create a global .markdownlint.json file in your home directory:

touch ~/.markdownlint.json

Add the following to ~/.markdownlint.json:

{
    "MD007": {
        "indent": 4
    },
    "MD013": false,
    "MD024": {
        "siblings_only": true
    },
    "MD033": false
}

Rules

  • MD007 — Unordered list indentation
    • Uses 4 spaces for nested unordered lists.
    • This provides consistent indentation and works well with GitHub Flavored Markdown.
  • MD013 — Line length
    • Disabled.
    • Markdownlint normally limits lines to 80 characters.
    • GFM does not require an 80-character line limit, so disabling this allows paragraphs and other content to remain on a single source line.
  • MD024 — Duplicate headings
    • Configured with siblings_only: true.
    • Allows the same heading name to appear in different sections.
    • Duplicate headings under the same parent are still flagged.
  • MD033 — Inline HTML
    • Disabled.
    • Allows HTML inside Markdown documents.
    • GitHub supports useful HTML elements such as <details>, <summary>, <kbd>, and <br>.

Configure VS Code

Add the following to your VS Code settings.json:

"markdownlint.configFile": "/Users/yourusername/.markdownlint.json",

Replace yourusername with your macOS username.

Markdownlint will now use the global configuration for your Markdown files.

Project-Specific Configuration

If you only want the rules to apply to a specific project, create .markdownlint.json in the root of the project instead:

my-project/
├── .markdownlint.json
├── README.md
└── ...

A project-level .markdownlint.json can be committed to Git with the rest of the project. This is especially useful for team projects because everyone who clones the repository can use the same Markdownlint rules.

It also allows individual projects to define their own Markdown standards instead of relying on each developer’s global VS Code configuration.