Markdown Style Guide

Linting: markdownlint

Projects MUST use markdownlint¹ to enforce consistent Markdown style.

npm install --save-dev markdownlint-cli@0.46.0
npx --package=markdownlint-cli@0.46.0 markdownlint '**/*.md'

Configuration (.markdownlint.json)

Projects MUST use the following base configuration:

{
  "default": true,
  "MD013": false,
  "MD033": false,
  "MD041": false
}

Disabled rules:

• MD013: Line length (Prettier² handles this)
• MD033: Inline HTML (sometimes needed)
• MD041: First line must be heading (not always applicable)

Formatting: Prettier

Projects MUST use Prettier² for Markdown formatting with the following configuration:

{
  "proseWrap": "always",
  "printWidth": 80,
  "tabWidth": 2
}

Why tabWidth 2

tabWidth controls the indentation Prettier² emits for nested list items, and markdownlint¹ rule MD007/ul-indent defaults to an expected indent of two spaces. Setting tabWidth to 4 makes the two mandatory tools contradict each other: Prettier writes four-space nested items and markdownlint then reports MD007/ul-indent [Expected: 2; Actual: 4] on the file Prettier just formatted, so no file can satisfy both. tabWidth: 2 keeps MD007 at its default and leaves the base .markdownlint.json above unchanged.

Projects that MUST use four-space indentation for portability with legacy Markdown parsers MUST relax the affected rule in .markdownlint.json rather than leaving the conflict in place:

{
  "MD007": { "indent": 4 }
}

Only MD007 needs relaxing. Prettier 3.9.6 applies tabWidth to continuation and nesting indentation only, and still emits a single space after every list marker, so the MD030/list-marker-space override shown in the upstream compatibility notes⁵ is unnecessary — setting it to 3 makes markdownlint¹ reject Prettier’s own output.

The trade-off is that MD007: { "indent": 4 } diverges from the markdownlint¹ default, so every consumer of the documentation must copy it; two-space indentation needs no configuration at all.

Line Length

Prose MUST wrap at 80 characters. URLs, code blocks, and tables MAY exceed this limit when necessary.

Headings

# Document Title (only one H1)

## Section

### Subsection

Headings MUST:

• Use ATX-style (#) not Setext-style (underlines)
• Have one blank line before and after
• Omit trailing punctuation

Lists

Nested list items MUST be indented by two spaces, matching the tabWidth: 2 Prettier² setting above and the markdownlint¹ MD007 default.

- Item one
- Item two
  - Nested item (2-space indent)
  - Another nested item
- Item three

1. First step
2. Second step
3. Third step

Code Blocks

Code blocks MUST specify the language:

```python
def hello():
    print("Hello, World!")
```

```bash
echo "Hello"
```

Inline code SHOULD be used for: variable_name, function(), ClassName

Diagrams: Mermaid

Projects SHOULD use Mermaid³ for diagrams in documentation. It renders in GitHub, GitLab, and most documentation systems.

When NOT to Use Mermaid

Projects SHOULD NOT use Mermaid³ for:

• Complex diagrams with many nodes (>20)
• Diagrams requiring precise positioning
• Diagrams with images/icons
• Highly customized styling

For complex diagrams, projects MAY use dedicated tools (Excalidraw⁶, draw.io⁷) and embed as images.

ASCII Diagrams

For simple diagrams that MUST work everywhere (including plain text viewers), projects MAY use ASCII art:

┌─────────────┐     ┌─────────────┐
│   Client    │────>│    API      │
└─────────────┘     └──────┬──────┘
                           │
                           v
                    ┌─────────────┐
                    │  Database   │
                    └─────────────┘

Link Checking

Projects SHOULD validate links using markdown-link-check⁴:

npm install --save-dev markdown-link-check@3.15.0
npx markdown-link-check@3.15.0 --config .markdown-link-check.json README.md

Configuration (.markdown-link-check.json)

{
  "ignorePatterns": [
    { "pattern": "^https://localhost" }
  ],
  "timeout": "20s",
  "retryOn429": true
}

Every invocation MUST pass this file explicitly: --config .markdown-link-check.json on the command line and config-file: .markdown-link-check.json for the GitHub Action below.

Pre-commit Configuration

Projects SHOULD configure pre-commit hooks to run markdownlint¹ and Prettier²:

repos:
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.46.0
    hooks:
      - id: markdownlint
        args: [--disable, MD013, MD033, MD041, --]

  - repo: https://github.com/pre-commit/mirrors-prettier
    rev: v4.0.0-alpha.8
    hooks:
      - id: prettier
        types: [markdown]

See pre-commit⁹ documentation for more information on configuring hooks.

CI Pipeline

Projects SHOULD run Markdown linting and link checking in CI. The following is a complete workflow, not a fragment: save it as .github/workflows/docs.yml and it runs as written.

name: Docs

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: DavidAnson/markdownlint-cli2-action@eb5ca3ab411449c66620fe7f1b3c9e10547144b0 # v18.0.0
        with:
          globs: "**/*.md"
      - uses: >- # v1
          gaurav-nelson/github-action-markdown-link-check@5c5dfc0ac2e225883c0e5f03a85311ec2830d368
        with:
          config-file: .markdown-link-check.json