Markdownlint Shared Configurations

A collection of reusable markdownlint base configurations for different use cases and project types.

Available Configurations

🎯 strict.jsonc

Recommended for: New projects, libraries, technical documentation requiring high consistency.

Enables all rules with strict settings for maximum consistency and quality. Enforces:

• 80-character line length limit
• ATX-style headings (#)
• Dash-style unordered lists (-)
• 2-space list indentation
• Backtick code fences
• Asterisk emphasis/strong
• Consistent horizontal rule style (---)

Usage:

{
  "extends": "@gfmio/config-markdownlint/strict.jsonc"
}

🌊 relaxed.jsonc

Recommended for: READMEs, personal projects, quick documentation.

Enables all rules but disables the most commonly problematic ones:

• No line length limit (MD013)
• Allows duplicate headings in different sections (MD024/siblings_only)
• Allows inline HTML (MD033)
• Allows bare URLs (MD034)
• Allows emphasis as heading replacement (MD036)
• Doesn't require first line to be heading (MD041)

Usage:

{
  "extends": "@gfmio/config-markdownlint/relaxed.jsonc"
}

🎨 style-guide.jsonc

Recommended for: Teams establishing style guidelines, enforcing consistency.

Focuses on style consistency rather than strictness. Uses "consistent" settings where possible, allowing teams to choose their own style while enforcing consistency:

• Consistent heading, list, code fence, and emphasis styles
• Proper whitespace and indentation rules
• No line length limit
• Allows duplicate headings in siblings

Usage:

{
  "extends": "@gfmio/config-markdownlint/style-guide.jsonc"
}

🐙 github-flavored.jsonc

Recommended for: GitHub repositories, projects using GitHub-flavored Markdown features.

Optimized for GitHub's Markdown rendering with:

• 120-character line length (comfortable for GitHub UI)
• Allows common GitHub HTML elements (details, summary, kbd, etc.)
• Fenced code blocks with backticks
• ATX-style headings
• Dash-style lists

Usage:

{
  "extends": "@gfmio/config-markdownlint/github-flavored.jsonc"
}

📚 documentation.jsonc

Recommended for: Documentation sites, wikis, knowledge bases, technical writing.

Balanced configuration for documentation projects:

• No line length limit (docs often have long paragraphs)
• Allows inline HTML for rich formatting
• Supports front matter titles
• Doesn't enforce strict duplicate heading rules
• Allows documents without top-level heading
• Consistent code and emphasis styles

Usage:

{
  "extends": "@gfmio/config-markdownlint/documentation.jsonc"
}

Installation & Usage

With markdownlint-cli2

1. Install markdownlint-cli2:

   npm install --save-dev markdownlint-cli2
   

With VS Code Extension

1. Install the extension: markdownlint

2. Install the shared config package:

   npm install --save-dev @gfmio/config-markdownlint
   

Or reference a config file:

{
  "markdownlint.customRules": [],
  "markdownlint.config": {}
}

And create .markdownlint.jsonc in your project root:

{
  "extends": "@gfmio/config-markdownlint/github-flavored.jsonc"
}

Direct File Copy

You can also copy any configuration file directly to your project:

cp /path/to/config-markdownlint/strict.jsonc /path/to/your/project/.markdownlint.jsonc

Extending Configurations

All configurations can be extended and customized:

{
  "extends": "@gfmio/config-markdownlint/strict.jsonc",
  "MD013": {
    "line_length": 100
  },
  "MD033": {
    "allowed_elements": ["br", "img"]
  }
}

Multiple Configuration Inheritance

You can extend multiple configurations (later ones override earlier ones):

{
  "extends": [
    "@gfmio/config-markdownlint/strict.jsonc",
    "./custom-overrides.jsonc"
  ]
}

Choosing the Right Configuration

| Project Type | Recommended Config | Why | |--------------|-------------------|-----| | New library/package | strict.jsonc | Establishes high quality standards from the start | | README only | relaxed.jsonc | Less friction for quick documentation | | GitHub project | github-flavored.jsonc | Optimized for GitHub's Markdown rendering | | Documentation site | documentation.jsonc | Balanced for long-form technical writing | | Team style guide | style-guide.jsonc | Enforces consistency while allowing team preferences |

CI/CD Integration

GitHub Actions

name: Lint Markdown

on: [push, pull_request]

jobs:
  markdown-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npx markdownlint-cli2 "**/*.md"

Pre-commit Hook (with husky + lint-staged)

package.json:

{
  "lint-staged": {
    "*.md": "markdownlint-cli2"
  }
}

.husky/pre-commit:

#!/bin/sh
npx lint-staged

Common Overrides

Allow Longer Lines

{
  "extends": "@gfmio/config-markdownlint/strict.jsonc",
  "MD013": {
    "line_length": 120
  }
}

Allow Specific HTML Elements

{
  "extends": "@gfmio/config-markdownlint/strict.jsonc",
  "MD033": {
    "allowed_elements": ["br", "details", "summary"]
  }
}

Disable Specific Rules

{
  "extends": "@gfmio/config-markdownlint/strict.jsonc",
  "MD041": false,
  "MD013": false
}

Inline Rule Control

You can temporarily disable rules in your Markdown files:

<!-- markdownlint-disable MD013 -->
This line can be as long as you want without triggering the line length rule.
<!-- markdownlint-enable MD013 -->

<!-- markdownlint-disable-next-line MD033 -->
<div>This HTML is allowed</div>

Contributing

Suggestions for new configurations or improvements to existing ones are welcome!

License

MIT

Resources

• markdownlint repository
• Rules reference
• markdownlint-cli2
• VS Code extension