markdown

Markdown Expert

Expert guidance for markdown linting, quality enforcement, and documentation best practices.

Markdownlint - Markdown Linter

What is markdownlint?

markdownlint is a static analysis tool that checks markdown files for:

• Style consistency
• Formatting issues
• Common mistakes
• Best practices violations
• Accessibility concerns

Integrated with:

• VS Code extension (real-time feedback)
• Command line (markdownlint-cli2)
• Git pre-commit hooks
• CI/CD pipelines

Installation

markdownlint-cli2 (Node.js-based, recommended):

npm install -g markdownlint-cli2

Verify installation:

markdownlint-cli2 --version

Basic Usage

Lint a single file:

markdownlint-cli2 README.md

Lint all markdown files recursively:

markdownlint-cli2 "**/*.md"

Fix auto-fixable issues:

markdownlint-cli2 --fix "**/*.md"

Custom configuration:

markdownlint-cli2 --config .markdownlint.jsonc "**/*.md"

Common Rules

Full rule list: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md

Configuration

Create .markdownlint.jsonc in repository root:

{
  // Default state for all rules
  "default": true,
  
  // MD013/line-length - Line length (disabled for long URLs, tables, code)
  "MD013": {
    "line_length": 120,
    "heading_line_length": 120,
    "code_block_line_length": 120,
    "code_blocks": false,
    "tables": false,
    "headings": true
  },
  
  // MD024/no-duplicate-heading - Multiple headings with same content
  "MD024": {
    "siblings_only": true  // Allow same heading in different sections
  },
  
  // MD033/no-inline-html - Inline HTML (allow for specific tags)
  "MD033": {
    "allowed_elements": ["br", "details", "summary", "sup", "sub"]
  },
  
  // MD040/fenced-code-language - Fenced code blocks should have language
  "MD040": true,
  
  // MD046/code-block-style - Code block style (fenced preferred)
  "MD046": {
    "style": "fenced"
  }
}

VS Code Integration

markdownlint extension provides real-time feedback.

Extension ID: DavidAnson.vscode-markdownlint

Install:

code --install-extension DavidAnson.vscode-markdownlint

Settings (settings.json):

{
  "markdownlint.config": {
    "default": true,
    "MD013": false
  }
}

Best Practices

1. Use fenced code blocks with language specifiers

   ```powershell
   Get-Process
   

2. Consistent heading hierarchy - Don't skip levels

   # H1
   ## H2
   ### H3
   

3. Surround headings with blank lines

   Previous paragraph.
   
   ## Heading
   
   Next paragraph.
   

4. End files with newline - Most rules expect this

5. Use consistent list markers

   • Use - for unordered lists
   • Use 1. for ordered lists

6. Add language to code blocks

   ```javascript
   console.log('Hello');
   ```
   

Common Issues and Fixes

Issue: MD009 - Trailing spaces

# Fix automatically
markdownlint-cli2 --fix "**/*.md"

Issue: MD012 - Multiple consecutive blank lines

# ❌ Bad
Paragraph 1.


Paragraph 2.

# ✅ Good
Paragraph 1.

Paragraph 2.

Issue: MD040 - Fenced code language

# ❌ Bad
```
code here
```

# ✅ Good
```javascript
code here
```

Issue: MD047 - Files should end with newline

• Most editors do this automatically
• Configure your editor to add final newline

Ignoring Rules

In configuration (.markdownlint.jsonc):

{
  "MD013": false  // Disable line length globally
}

In-file comments (use sparingly):

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

Note: Only disable rules with good reason. Fix the markdown instead.

Quick Fix Script

Run this to auto-fix common issues:

# Fix all markdown files in repository
markdownlint-cli2 --fix "**/*.md"

# Fix specific directory
markdownlint-cli2 --fix "docs/**/*.md"

Quality Standards

All markdown files should adhere to:

• ✅ Consistent heading hierarchy (no skipped levels)
• ✅ Fenced code blocks with language specifiers
• ✅ Proper blank lines around headings, lists, and code blocks
• ✅ No trailing spaces
• ✅ Files end with newline
• ✅ Line length limits (120 chars for content)
• ✅ Consistent list markers