Markdownlint Configuration

Markdownlint Configuration

Master markdownlint configuration including rule management, configuration files, inline comment directives, style inheritance, and schema validation for consistent Markdown linting.

Overview

Markdownlint is a Node.js style checker and linter for Markdown/CommonMark files. It helps enforce consistent formatting and style across Markdown documentation by providing a comprehensive set of rules that can be customized through configuration files or inline comments.

Installation and Setup

Basic Installation

Install markdownlint in your project:

npm install --save-dev markdownlint markdownlint-cli
# or
pnpm add -D markdownlint markdownlint-cli
# or
yarn add -D markdownlint markdownlint-cli

Verify Installation

npx markdownlint --version

Configuration File Structure

Basic .markdownlint.json

Create a .markdownlint.json file in your project root:

{
  "default": true,
  "MD003": { "style": "atx_closed" },
  "MD007": { "indent": 4 },
  "no-hard-tabs": false,
  "whitespace": false
}

This configuration:

• Enables all default rules via "default": true
• Configures MD003 (heading style) to use ATX closed format
• Sets MD007 (unordered list indentation) to 4 spaces
• Disables the no-hard-tabs rule
• Disables all whitespace rules

Rule Naming Conventions

Rules can be referenced by their ID (MD###) or friendly name:

{
  "MD001": false,
  "heading-increment": false,
  "MD003": { "style": "atx" },
  "heading-style": { "style": "atx" },
  "no-inline-html": {
    "allowed_elements": ["strong", "em", "br"]
  }
}

Both ID and friendly name work identically.

Configuration Options

Enable/Disable All Rules

{
  "default": true
}

When "default": false, only explicitly enabled rules are active:

{
  "default": false,
  "MD001": true,
  "MD003": { "style": "atx" },
  "line-length": true
}

Rule-Specific Parameters

Heading Style (MD003)

{
  "heading-style": {
    "style": "atx"
  }
}

Options: "atx", "atx_closed", "setext", "setext_with_atx", "setext_with_atx_closed"

Unordered List Style (MD004)

{
  "ul-style": {
    "style": "asterisk"
  }
}

Options: "asterisk", "dash", "plus", "consistent", "sublist"

List Indentation (MD007)

{
  "ul-indent": {
    "indent": 4,
    "start_indented": true
  }
}

Line Length (MD013)

{
  "line-length": {
    "line_length": 100,
    "heading_line_length": 120,
    "code_block_line_length": 120,
    "code_blocks": true,
    "tables": false,
    "headings": true,
    "strict": false,
    "stern": false
  }
}

No Trailing Spaces (MD009)

{
  "no-trailing-spaces": {
    "br_spaces": 2,
    "list_item_empty_lines": false,
    "strict": false
  }
}

No Inline HTML (MD033)

{
  "no-inline-html": {
    "allowed_elements": [
      "strong",
      "em",
      "br",
      "sub",
      "sup",
      "kbd",
      "details",
      "summary"
    ]
  }
}

Horizontal Rule Style (MD035)

{
  "hr-style": {
    "style": "---"
  }
}

Options: "---", "***", "___", or custom like "- - -"

First Line Heading (MD041)

{
  "first-line-heading": {
    "level": 1,
    "front_matter_title": ""
  }
}

Required Headings

{
  "required-headings": {
    "headings": [
      "# Title",
      "## Description",
      "## Examples",
      "## Resources"
    ]
  }
}

Proper Names (MD044)

{
  "proper-names": {
    "names": [
      "JavaScript",
      "TypeScript",
      "GitHub",
      "markdownlint",
      "npm"
    ],
    "code_blocks": false
  }
}

Inline Configuration Comments

Disable Rules for Entire File

<!-- markdownlint-disable-file -->

# This file has no linting applied

Any markdown content here will not be checked.

Disable Specific Rules for File

<!-- markdownlint-disable-file MD013 MD033 -->

# Long lines and HTML are allowed in this file

This line can be as long as you want without triggering MD013.

<div>Inline HTML is also allowed</div>

Disable Rules Temporarily

<!-- markdownlint-disable MD033 -->

<div class="custom-block">
  HTML content here
</div>

<!-- markdownlint-enable MD033 -->

Regular markdown content with rules enforced.

Disable for Single Line

This line follows all rules.

Long line that exceeds limit <!-- markdownlint-disable-line MD013 -->

This line follows all rules again.

Disable for Next Line

<!-- markdownlint-disable-next-line MD013 -->
This is a very long line that would normally trigger the line-length rule but won't because of the comment above.

This line follows normal rules.

Capture and Restore Configuration

<!-- markdownlint-capture -->
<!-- markdownlint-disable -->

Any violations allowed here.

<!-- markdownlint-restore -->

Back to original configuration.

Configure Rules Inline

<!-- markdownlint-configure-file {
  "line-length": {
    "line_length": 120
  },
  "no-inline-html": {
    "allowed_elements": ["strong", "em"]
  }
} -->

# Document Title

Rest of document follows inline configuration.

Configuration File Formats

JSON Configuration

.markdownlint.json:

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true,
  "MD003": { "style": "atx" },
  "MD007": { "indent": 2 },
  "MD013": {
    "line_length": 100,
    "code_blocks": false
  },
  "MD033": {
    "allowed_elements": ["br", "strong", "em"]
  }
}

YAML Configuration

.markdownlint.yaml:

default: true
MD003:
  style: atx
MD007:
  indent: 2
MD013:
  line_length: 100
  code_blocks: false
MD033:
  allowed_elements:
    - br
    - strong
    - em

JavaScript Configuration

.markdownlint.js:

module.exports = {
  default: true,
  MD003: { style: "atx" },
  MD007: { indent: 2 },
  MD013: {
    line_length: 100,
    code_blocks: false
  },
  MD033: {
    allowed_elements: ["br", "strong", "em"]
  }
};

Configuration Inheritance

Extending Base Configurations

Create a base configuration:

base.json:

{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}

Extend it in your project:

custom.json:

{
  "extends": "base.json",
  "no-inline-html": false,
  "line-length": {
    "line_length": 120
  }
}

Using Predefined Styles

Markdownlint includes predefined style configurations:

{
  "extends": "markdownlint/style/relaxed"
}

Available styles:

• markdownlint/style/relaxed - Less strict rules
• markdownlint/style/prettier - Compatible with Prettier

Schema Validation

Enable IDE Support

Include the $schema property for autocomplete and validation:

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json",
  "default": true
}

This enables:

• Autocomplete for rule names
• Validation of configuration values
• Inline documentation in supported editors

Project-Specific Configurations

Per-Directory Configuration

Place .markdownlint.json in specific directories:

project/
├── .markdownlint.json          # Root config
├── docs/
│   ├── .markdownlint.json      # Docs-specific config
│   └── guides/
│       └── .markdownlint.json  # Guides-specific config

Monorepo Configuration

Root .markdownlint.json:

{
  "default": true,
  "line-length": {
    "line_length": 100
  }
}

Package-specific packages/api/docs/.markdownlint.json:

{
  "extends": "../../../.markdownlint.json",
  "no-inline-html": {
    "allowed_elements": ["code", "pre", "div"]
  }
}

Common Configuration Patterns

Strict Documentation Standards

{
  "default": true,
  "heading-style": { "style": "atx" },
  "ul-style": { "style": "dash" },
  "ol-prefix": { "style": "ordered" },
  "line-length": {
    "line_length": 80,
    "strict": true
  },
  "no-trailing-spaces": {
    "strict": true
  },
  "no-inline-html": false,
  "first-line-heading": {
    "level": 1
  },
  "required-headings": {
    "headings": [
      "# Title",
      "## Description",
      "## Usage",
      "## API"
    ]
  }
}

Relaxed Blog/Article Style

{
  "default": true,
  "line-length": false,
  "no-inline-html": {
    "allowed_elements": [
      "img",
      "a",
      "strong",
      "em",
      "br",
      "div",
      "span"
    ]
  },
  "no-duplicate-heading": {
    "siblings_only": true
  },
  "first-line-heading": false,
  "single-title": false
}

Technical Documentation

{
  "default": true,
  "line-length": {
    "line_length": 120,
    "code_blocks": false,
    "tables": false
  },
  "no-inline-html": {
    "allowed_elements": [
      "details",
      "summary",
      "kbd",
      "sub",
      "sup",
      "br"
    ]
  },
  "code-block-style": {
    "style": "fenced"
  },
  "code-fence-style": {
    "style": "backtick"
  },
  "emphasis-style": {
    "style": "asterisk"
  },
  "strong-style": {
    "style": "asterisk"
  }
}

README Template

{
  "default": true,
  "line-length": {
    "line_length": 100,
    "tables": false,
    "code_blocks": false
  },
  "no-inline-html": {
    "allowed_elements": [
      "img",
      "br",
      "details",
      "summary",
      "sup"
    ]
  },
  "required-headings": {
    "headings": [
      "# *",
      "## Installation",
      "## Usage",
      "## License"
    ]
  },
  "first-line-heading": {
    "level": 1
  }
}

When to Use This Skill

• Setting up markdownlint in new projects
• Configuring linting rules for documentation
• Creating custom rule configurations for teams
• Troubleshooting configuration issues
• Establishing Markdown style guides
• Migrating from other Markdown linters
• Enforcing consistent documentation standards
• Configuring monorepo Markdown linting

Best Practices

1. Use Schema Validation - Always include $schema for IDE support
2. Start with Defaults - Begin with "default": true and disable selectively
3. Document Exceptions - Comment why specific rules are disabled
4. Consistent Naming - Use either rule IDs or friendly names, not both
5. Version Control Config - Commit .markdownlint.json to repository
6. Team Agreement - Discuss rule changes with team before applying
7. Progressive Adoption - Gradually enable stricter rules over time
8. Test Changes - Run linter after configuration changes
9. Use Inheritance - Leverage extends for shared configurations
10. Inline Sparingly - Prefer file-level config over inline comments
11. Monitor Rule Updates - Review new rules in markdownlint updates
12. Environment-Specific - Use different configs for different doc types
13. Automation Integration - Include linting in pre-commit hooks
14. Regular Review - Periodically review and update configurations
15. Clear Comments - Add comments explaining complex configurations

Common Pitfalls

1. Conflicting Rules - Enabling contradictory rules (e.g., different heading styles)
2. Over-Configuration - Specifying too many inline disable comments
3. Missing Schema - Not including $schema for validation
4. Incorrect Paths - Using wrong paths in extends property
5. Rule Name Typos - Misspelling rule names (fails silently)
6. JSON Syntax Errors - Invalid JSON breaks configuration parsing
7. Overly Strict - Enabling strict rules without team buy-in
8. Ignoring Warnings - Dismissing legitimate style issues
9. No Base Config - Not establishing project-wide defaults
10. Hardcoded Values - Not using variables for repeated values
11. Stale Configurations - Not updating after markdownlint upgrades
12. Missing Allowed Elements - Blocking necessary HTML elements
13. Inconsistent Inheritance - Different base configs across projects
14. No Testing - Not testing configuration before committing
15. Unclear Disable Reasons - Using disable without explanation

Resources

• markdownlint GitHub Repository
• markdownlint Rules Documentation
• Configuration Schema
• markdownlint-cli Documentation
• Custom Rules Guide