Introduction

Welcome to mdbook-lint, a fast and comprehensive markdown linter designed specifically for mdBook projects.

What is mdbook-lint

mdbook-lint is a command-line tool and mdBook preprocessor that helps you maintain high-quality markdown documentation by detecting common issues, enforcing consistent style, and providing mdBook-specific linting rules.

Key Features

• Fast Performance: Built in Rust for speed and efficiency
• Comprehensive Rule Set: 55 standard markdown rules, 18 mdBook-specific rules, 17 ADR rules, and 10 content rules (100 total)
• Flexible Integration: Works as a standalone CLI tool or as an mdBook preprocessor
• Rustdoc Linting: Lint module-level documentation (//! comments) in Rust source files
• ADR Validation: Validate Architecture Decision Records (Nygard and MADR 4.0 formats)
• Configurable: Customize rules and behavior through configuration files
• Zero Dependencies: Self-contained binary with no external dependencies

Why Use mdbook-lint

Documentation quality matters. Consistent, well-formatted markdown makes your documentation:

• More readable for contributors and users
• Easier to maintain across large documentation projects
• More professional in appearance and structure
• Less prone to rendering issues in mdBook

Getting Started

Ready to improve your documentation quality? Head over to the Installation guide to get started, or jump straight to Getting Started for a quick walkthrough.

Community and Support

mdbook-lint is open source and welcomes contributions. Visit our GitHub repository to:

• Report issues
• Request features
• Contribute code
• Browse the source

For development information, see our Contributing guide.

Acknowledgments

mdbook-lint builds on the excellent work of:

• markdownlint - The original Node.js markdown linter that defined the standard rule set (MD001-MD059)
• rumdl - A fast Rust markdown linter that inspired our implementation approach

We aim to be compatible with markdownlint's rule definitions while adding mdBook-specific functionality.

Installation

mdbook-lint can be installed through several methods depending on your needs.

Homebrew (macOS/Linux)

If you use Homebrew, you can install mdbook-lint from the tap:

brew tap joshrotenberg/brew
brew install mdbook-lint

From Crates.io

Install via Cargo from crates.io:

cargo install mdbook-lint

By default, this includes all rule sets:

• standard - 55 markdown syntax rules (MD001-MD060)
• mdbook - 18 mdBook-specific rules (MDBOOK001-MDBOOK025)
• content - 10 content quality rules (CONTENT001-CONTENT011)

To install without specific rule sets:

# Without content rules
cargo install mdbook-lint --no-default-features --features standard,mdbook,lsp

# Only standard markdown rules
cargo install mdbook-lint --no-default-features --features standard,lsp

From Source

To install the latest development version or contribute to the project:

git clone https://github.com/joshrotenberg/mdbook-lint.git
cd mdbook-lint
cargo install --path crates/mdbook-lint-cli

The repository root is a virtual workspace manifest, so the path must point at the mdbook-lint-cli crate rather than at ..

Pre-built Binaries

Pre-built binaries for common platforms are available on the GitHub releases page.

Download the appropriate binary for your platform and add it to your PATH.

Requirements

• Rust 1.88 or later (if building from source)
• No runtime dependencies required

Verification

After installation, verify that mdbook-lint is working correctly:

mdbook-lint --version

The output shows the installed version:

mdbook-lint x.y.z

Next Steps

Once installed, head to the Getting Started guide to learn how to use mdbook-lint with your projects.

Getting Started

This guide will walk you through using mdbook-lint for the first time.

Quick Start

The fastest way to get started is to run mdbook-lint on some markdown files:

# Lint a single file
mdbook-lint lint README.md

# Lint multiple files
mdbook-lint lint src/*.md docs/*.md

# Lint all markdown files in a directory
mdbook-lint lint .

# Auto-fix violations where possible
mdbook-lint lint --fix src/*.md

Start with the Baseline Preset

Existing documentation often produces too many findings when every stable rule is enabled at once. For incremental CI adoption, start with the curated baseline preset:

mdbook-lint lint --preset baseline docs/

Or commit the selection in .mdbook-lint.toml:

preset = "baseline"
fail-on-warnings = true

The preset contains a small, versioned set of stable structural, syntax, and whitespace checks. Inspect its exact membership with mdbook-lint rules --preset baseline. You can subtract a project-specific rule with disabled-rules or --disable. When the project is ready for the complete stable ruleset, remove preset = "baseline".

Understanding the Output

When mdbook-lint finds issues, it will display them like this:

README.md:15:1: MD013: Line length (line too long, 85 > 80)
src/intro.md:3:1: MD001: Heading levels should only increment by one level at a time

Each line shows:

• File and location: filename:line:column
• Rule ID: The specific rule that was violated (e.g., MD013)
• Description: What the issue is and how to fix it

Your First Configuration

Create a .mdbook-lint.toml file in your project root:

# Fail the build on warnings
fail-on-warnings = true

# Disable rules that don't fit your project
disabled-rules = ["MD013"]  # Allow long lines

# Configure specific rules
[MD007]
indent = 4  # Use 4-space indentation for lists

Using with mdBook

To integrate mdbook-lint with your mdBook project:

1. Add to book.toml:

   [preprocessor.lint]
   

2. Build your book:

   
   mdbook build
   

mdbook-lint will now check your markdown files every time you build your book.

Choosing Your Integration: You can run mdbook-lint either as an mdBook preprocessor (shown above) OR as a standalone tool in CI. See CI vs Preprocessor to understand when to use each approach.

Automatic Fixing

mdbook-lint can automatically fix some common violations:

# Fix violations automatically
mdbook-lint lint --fix docs/

# Preview what would be fixed without applying changes
mdbook-lint lint --fix --dry-run docs/

# Apply all fixes, including potentially risky ones
mdbook-lint lint --fix-unsafe docs/

Currently supported fixes include:

• MD009: Trailing spaces
• MD010: Hard tabs → spaces
• MD012: Multiple blank lines
• MD018/MD019: Heading spacing issues
• MD022: Blank lines around headings
• MD023: Indented headings
• MD027: Blockquote spacing
• MD030: List marker spacing
• MD034: Bare URLs
• MD047: Missing trailing newline
• And more!

Common Workflow

Here's a typical workflow for using mdbook-lint:

1. Initial setup: Add configuration file and run first lint
2. Auto-fix simple issues: Use --fix to handle common problems
3. Fix remaining issues: Address structural problems manually
4. Customize rules: Disable rules that don't fit your style
5. Integrate with build: Add to mdBook or CI pipeline
6. Maintain quality: Regular linting keeps documentation clean

Exploring Rules

To see all available rules:

# List all rules
mdbook-lint rules

# Show detailed rule descriptions
mdbook-lint rules --detailed

# Filter rules by category
mdbook-lint rules --category structure

# Explain the low-noise baseline preset
mdbook-lint rules --preset baseline --detailed

Next Steps

• Learn about Configuration options
• Explore CLI Usage in detail
• Set up mdBook Integration
• Browse the Rules Reference

Configuration

mdbook-lint supports multiple configuration formats and provides flexible options for customizing linting behavior.

Configuration File Formats

mdbook-lint automatically detects and supports multiple configuration formats:

• TOML: .mdbook-lint.toml or mdbook-lint.toml (recommended)
• YAML: .mdbook-lint.yaml or .mdbook-lint.yml
• JSON: .mdbook-lint.json
• markdownlint: .markdownlint.json (for compatibility)

Configuration Discovery

mdbook-lint searches for configuration files in the following order:

1. Current directory
2. Parent directories (recursively up to root)

The first configuration file found is used. To use a specific file instead of discovery, pass --config <FILE> to lint, fix, or rustdoc.

Basic Configuration

For incremental adoption in an existing project, select the maintained low-noise baseline instead of copying a rule allowlist:

preset = "baseline"

Inspect the exact membership with mdbook-lint rules --preset baseline. Remove the setting to move to the complete stable default ruleset.

TOML Format (Recommended)

# Global settings
fail-on-warnings = false
fail-on-errors = true
disabled-rules = ["MD013", "MD033"]
enabled-rules = ["MD001", "MD002"]

# Rule-specific configuration
[MD007]
indent = 2

[MD013]
line-length = 120
code-blocks = false

YAML Format

fail-on-warnings: false
fail-on-errors: true
disabled-rules:
  - MD013
  - MD033
enabled-rules:
  - MD001
  - MD002

MD007:
  indent: 2

MD013:
  line-length: 120
  code-blocks: false

JSON Format

{
  "fail-on-warnings": false,
  "fail-on-errors": true,
  "disabled-rules": ["MD013", "MD033"],
  "enabled-rules": ["MD001", "MD002"],
  "MD007": {
    "indent": 2
  },
  "MD013": {
    "line-length": 120,
    "code-blocks": false
  }
}

Advanced Rule Control

The [rules] Section

The [rules] section provides fine-grained control over which rules run:

[rules]
# Disable all rules by default
default = false

# Only enable specific rules
[rules.enabled]
MD001 = true
MD002 = true
MD013 = true

# Rule-specific configuration still works
[MD013]
line-length = 120

This is particularly useful for:

• Gradual adoption of linting rules
• Testing specific rules
• Creating minimal rule sets

Category-Based Rule Management

Control entire categories of rules at once:

# Enable/disable rule categories
enabled-categories = ["headings", "lists"]
disabled-categories = ["whitespace"]

# Individual rules override categories
enabled-rules = ["MD009"]  # Enable even though whitespace is disabled
disabled-rules = ["MD001"]  # Disable even though headings is enabled

Available categories:

• headings - Heading-related rules
• lists - List formatting rules
• whitespace - Whitespace and blank line rules
• code - Code block and inline code rules
• style - General style rules
• links - Link and reference rules
• mdbook - mdBook-specific rules

markdownlint Compatibility

mdbook-lint can read .markdownlint.json files for compatibility:

{
  "default": false,
  "MD001": true,
  "MD013": {
    "line_length": 120,
    "code_blocks": false
  }
}

Enable full markdownlint compatibility mode:

markdownlint-compatible = true

This disables rules that are disabled by default in markdownlint.

Global Configuration Options

Ignoring Paths

Use ignore-paths to skip files entirely before any rule runs. Patterns are glob-style and behave like .gitignore entries:

ignore-paths = [
    "vendor/",        # a trailing slash ignores everything under a directory
    "drafts/**",      # or use ** explicitly
    "*.backup.md",    # a slash-less pattern matches at any depth
]

* does not cross path separators; ** does. Both ignore-paths and ignore_paths spellings are accepted.

Configuration Precedence

Configuration is resolved in the following order (later overrides earlier):

1. Built-in defaults
2. Configuration file (.mdbook-lint.toml, etc.)
3. mdBook preprocessor config (in book.toml)
4. Command-line arguments

mdBook Integration

When used as an mdBook preprocessor, configuration can be specified in book.toml:

[preprocessor.lint]
preset = "baseline"
fail-on-warnings = true
disabled-rules = ["MD025"]

[preprocessor.lint.MD013]
line-length = 100

Example Configurations

Baseline - Incremental Adoption

preset = "baseline"
fail-on-warnings = true

Strict - All Rules with Custom Settings

fail-on-warnings = true
fail-on-errors = true

[MD007]
indent = 2

[MD013]
line-length = 80
code-blocks = true
tables = true
headings = true

[MD024]
siblings-only = true

[MD029]
style = "ordered"

mdBook Projects

# Disable rules that conflict with mdBook conventions
disabled-rules = [
    "MD025",  # Multiple H1s are OK in books
    "MD041",  # First line doesn't need to be H1
]

# mdBook-specific rules
enabled-categories = ["mdbook"]

[MD013]
line-length = 100  # Longer lines for documentation

Progressive Adoption

Start with a few rules and gradually enable more:

# Phase 1: Start with formatting rules
[rules]
default = false

[rules.enabled]
MD009 = true  # Trailing spaces
MD010 = true  # Hard tabs
MD012 = true  # Multiple blank lines

# Phase 2: Add heading rules (uncomment when ready)
# MD001 = true  # Heading increment
# MD003 = true  # Heading style

# Phase 3: Add more rules...

Migration from markdownlint

If migrating from markdownlint, start with compatibility mode:

markdownlint-compatible = true

# Then gradually customize...
[MD013]
line-length = 100

Generating Configuration Files

Use the init command to generate a configuration file:

# Generate minimal configuration
mdbook-lint init

# Generate comprehensive configuration with every rule documented
mdbook-lint init --include-all

# Generate in a different format
mdbook-lint init --format yaml
mdbook-lint init --format json

Configuration Examples

For real-world configuration examples:

• example-mdbook-lint.toml - Comprehensive reference with all rules documented and commented
• docs/.mdbook-lint.toml - Real-world example used by this project's own documentation
• Baseline - Incremental CI adoption
• Strict - Publication and CI gates
• Relaxed - Personal projects and early drafts
• API documentation - Generated and hand-written API references
• Tutorial - Step-by-step learning material

Configuration Validation

To validate your configuration:

# Check if configuration file is valid
mdbook-lint check .mdbook-lint.toml

# List the available rules and their categories
mdbook-lint rules

Next Steps

• Configuration Reference - Complete list of options
• Rules Reference - All rules and their configurations
• CLI Usage - Command-line options

CLI Usage

This page documents the command-line interface for mdbook-lint.

Basic Commands

preprocessor

Run as an mdBook preprocessor (reads from stdin, writes to stdout). This is the mode mdBook invokes; you normally do not run it by hand.

mdbook-lint preprocessor

See mdBook Integration for details.

lint

Lint markdown files and directories.

mdbook-lint lint [OPTIONS] [FILES]...

fix

Automatically fix issues in markdown files (shorthand for lint --fix).

mdbook-lint fix [OPTIONS] [FILES]...

rules

List available linting rules by category.

mdbook-lint rules [OPTIONS]

check

Check a configuration file for validity.

mdbook-lint check <CONFIG>

init

Generate a default configuration file.

mdbook-lint init [OPTIONS]

supports

Check whether the preprocessor supports a given renderer (used by mdBook).

mdbook-lint supports <RENDERER>

rustdoc

Lint module-level documentation (//! comments) in Rust source files.

mdbook-lint rustdoc [OPTIONS] [PATHS]...

See Rustdoc Linting for detailed documentation.

lsp

Run as a Language Server Protocol (LSP) server. Available only when mdbook-lint is built with the lsp feature.

mdbook-lint lsp [OPTIONS]

help

Show help information.

mdbook-lint help [COMMAND]

Options

Global Options

• -h, --help: Print help information
• -V, --version: Print version information
• -v, --verbose: Enable verbose output
• -q, --quiet: Suppress non-error output

Lint Options

• --config <FILE>: Use specific configuration file
• --fail-on-warnings: Exit with error code on warnings
• --disable <RULES>: Disable specific rules (comma-separated)
• --enable <RULES>: Enable only specific rules (comma-separated)
• --preset <NAME>: Use a curated rule preset (baseline)
• --fix: Automatically fix violations where possible
• --fix-unsafe: Apply all fixes, including potentially unsafe ones
• --dry-run: Show what would be fixed without applying changes (requires --fix or --fix-unsafe)
• --no-backup: Skip creating backup files when applying fixes
• --output <FORMAT>: Output format (default, json, github, sarif)
• --output-file <PATH>: Write the report to a file instead of stdout, used with --output sarif
• --color <WHEN>: Control colored output (auto, always, never)

Rules Options

• -d, --detailed: Show detailed information about each rule
• -c, --category <CATEGORY>: Filter by rule category
• -p, --provider <PROVIDER>: Show only rules from a specific provider
• --standard-only: Show only standard rules (MD001-MD059)
• --mdbook-only: Show only mdBook-specific rules
• --preset <NAME>: Show only rules in a curated preset
• --format <FORMAT>: Output format (default, json)
• --json: Output in JSON format (shorthand for --format json)

For linting commands, --preset baseline may be combined with --disable, which subtracts rules from the preset. It conflicts with --enable, --standard-only, and --mdbook-only where those flags are available because they choose a different base rule set.

Output Format

By default, mdbook-lint displays violations in a cargo/rustc-style format with colors:

error[MD001]: Expected heading level 2 but got level 3
  --> src/chapter.md:15:1
     |
  15 | ### Skipped heading level
     | ^^^ heading-increment

warning[MD009]: Trailing spaces detected
  --> src/intro.md:8:42
     |
   8 | This line has trailing spaces   
     |                                  ^ no-trailing-spaces

Found: 1 error(s), 1 warning(s)

Output Formats

• default: Colored, human-readable format (shown above)
• JSON: Machine-readable JSON output
• GitHub: GitHub Actions annotation format

Controlling Colors

Use --color to control colored output:

# Auto-detect (default) - colors when terminal supports it
mdbook-lint lint docs/

# Always use colors (useful for CI with color support)
mdbook-lint lint --color always docs/

# Never use colors (useful for piping to files)
mdbook-lint lint --color never docs/ > report.txt

Examples

# Lint current directory
mdbook-lint lint .

# Lint specific files
mdbook-lint lint README.md src/chapter1.md

# Lint with custom config
mdbook-lint lint --config custom-lint.toml src/

# Auto-fix violations where possible
mdbook-lint lint --fix docs/

# Preview fixes without applying them
mdbook-lint lint --fix --dry-run docs/

# Apply all fixes including potentially unsafe ones
mdbook-lint lint --fix-unsafe docs/

# Fix without creating backup files
mdbook-lint lint --fix --no-backup docs/

# Show all rules with descriptions
mdbook-lint rules --detailed

# Lint and fail on warnings
mdbook-lint lint --fail-on-warnings docs/

Exit Codes

• 0: Success (no errors)
• 1: Linting errors found
• 2: Invalid arguments or configuration

Next Steps

• Learn about mdBook Integration
• See Configuration Reference for all options

Rustdoc Linting

The rustdoc subcommand extracts and lints module-level documentation comments (//!) from Rust source files. This helps maintain high-quality documentation in your Rust crates.

Basic Usage

# Lint a single file
mdbook-lint rustdoc src/lib.rs

# Lint all Rust files in a directory (recursive)
mdbook-lint rustdoc src/

# Lint the entire crate
mdbook-lint rustdoc .

How It Works

The rustdoc command:

1. Finds all .rs files in the specified paths (recursively for directories)
2. Extracts module-level documentation (//! comments) from each file
3. Converts the documentation to markdown
4. Lints the markdown using standard rules
5. Maps violation line numbers back to the original source locations

What Gets Extracted

Only module-level documentation comments are extracted:

#![allow(unused)]
fn main() {
//! This line IS extracted (module-level doc)
//! This line IS extracted too

/// This line is NOT extracted (item-level doc)
fn example() {}

// This line is NOT extracted (regular comment)
}

The extraction stops when it encounters:

• A regular comment (//)
• Any non-comment code
• End of file

Default Disabled Rules

Some rules are disabled by default for rustdoc because they don't apply well to documentation comments:

You can re-enable these rules if needed:

mdbook-lint rustdoc --enable MD041,MD025 src/

Options

The rustdoc command supports most of the same options as lint:

# Use a specific configuration file
mdbook-lint rustdoc --config .mdbook-lint.toml src/

# Disable specific rules
mdbook-lint rustdoc --disable MD013,MD033 src/

# Enable only specific rules
mdbook-lint rustdoc --enable MD001,MD003,MD018 src/

# Output as JSON
mdbook-lint rustdoc --output json src/

# Fail on warnings (useful in CI)
mdbook-lint rustdoc --fail-on-warnings src/

# Verbose output showing which files are checked
mdbook-lint rustdoc --verbose src/

Directory Handling

When given a directory, the command:

• Recursively finds all .rs files
• Skips hidden directories (starting with .)
• Skips the target/ directory
• Processes files in parallel for performance

# This will skip .git/, target/, and any hidden directories
mdbook-lint rustdoc .

Example Output

warning[MD018]: No space after hash on atx style heading
  --> src/lib.rs:5:3
     |
   5 | //! ##Bad heading
     |   ^ no-missing-space-atx

warning[MD032]: Lists should be surrounded by blank lines
  --> src/parser.rs:12:1
     |
  12 | //! - First item
     | ^^^ blanks-around-lists

Found: 2 warning(s)

Note how the line numbers point to the actual source file locations, making it easy to find and fix issues.

CI Integration

GitHub Actions

- name: Lint rustdoc
  run: mdbook-lint rustdoc --fail-on-warnings --output github src/

The --output github format produces GitHub Actions annotations that appear inline in pull request diffs.

Generic CI

- name: Lint rustdoc
  run: mdbook-lint rustdoc --fail-on-warnings .

Common Patterns

Linting Before Publishing

Add to your CI pipeline to catch documentation issues before publishing:

# In your CI script
cargo fmt --check
cargo clippy -- -D warnings
cargo test
mdbook-lint rustdoc --fail-on-warnings .
cargo publish --dry-run

Workspace Projects

For Cargo workspaces, lint each crate:

mdbook-lint rustdoc crates/

Or lint specific crates:

mdbook-lint rustdoc crates/core/src crates/cli/src

Combining with Regular Linting

If you have both a Rust library and an mdBook:

# Lint the book
mdbook-lint lint docs/

# Lint the rustdoc
mdbook-lint rustdoc src/

Limitations

• Only extracts //! (module-level) documentation, not /// (item-level)
• Does not parse doc attributes (#![doc = "..."])
• Code blocks inside documentation are not validated for correctness (use cargo test --doc for that)

Tips for Better Rustdoc

1. Use headings consistently: Stick to conventional sections like # Examples, # Panics, # Errors, # Safety

2. Include code examples: They serve as both documentation and tests

   #![allow(unused)]
   fn main() {
   //! # Examples
   //!
   //! ```rust
   //! let result = my_function(42);
   //! assert_eq!(result, 84);
   //! ```
   }

3. Keep line lengths reasonable: Long lines in doc comments are hard to read in source

4. Use proper markdown: Lists need blank lines around them, headings need proper formatting

Next Steps

• See CLI Usage for all command options
• See Configuration for configuring rules
• See CI vs Preprocessor for CI best practices

mdBook Integration

mdbook-lint can run as an mdBook preprocessor, so every chapter is checked as part of mdbook build and mdbook serve. The preprocessor reports diagnostics without changing chapter content.

If you are deciding between build-time checks and a separate CI lint step, see CI vs Preprocessor.

Installation

Install mdbook-lint where mdBook can find it on PATH:

cargo install mdbook-lint

Prebuilt binaries are also available from GitHub Releases.

Verify the installation before configuring the book:

mdbook-lint --version
mdbook --version

Basic setup

Add the preprocessor to book.toml:

[preprocessor.lint]

mdBook derives the mdbook-lint command from the lint preprocessor name. You can make the command explicit if needed:

[preprocessor.lint]
command = "mdbook-lint"

The preprocessor now runs during normal mdBook commands:

mdbook build
mdbook serve
mdbook test

By default, warnings are reported without failing the build. Errors fail the build.

Configuration

There are two supported configuration sources for preprocessor mode:

1. A discovered mdbook-lint configuration file, preferably .mdbook-lint.toml.
2. Supported keys in [preprocessor.lint] in book.toml.

The external file is the place for rule-specific settings and the broader CLI configuration surface:

# .mdbook-lint.toml
fail-on-warnings = false
disabled-rules = ["MD013", "MD033"]

[MD024]
siblings_only = true

[MD040]
language_optional = false

See Configuration for all global settings and rule-specific syntax.

Supported book.toml keys

The [preprocessor.lint] table accepts these mdbook-lint settings:

For example:

[preprocessor.lint]
preset = "baseline"
fail-on-warnings = true
disabled-rules = ["MD014"]
disabled-categories = ["whitespace"]

Rule-specific tables and options such as ignore-paths belong in the external configuration file. They are not read from book.toml.

Configuration precedence

Preprocessor configuration is resolved in this order, with later supported values overriding earlier values:

1. Built-in defaults.
2. The first configuration file discovered from the book root upward.
3. [preprocessor.lint] in book.toml.

The discovery order at each directory is:

1. .mdbook-lint.toml
2. mdbook-lint.toml
3. .mdbook-lint.yaml
4. .mdbook-lint.yml
5. .mdbook-lint.json

The CLI --config option applies to standalone commands such as mdbook-lint lint; mdBook does not pass it to the preprocessor.

Environment variables

mdbook-lint does not provide environment-variable configuration overrides. Set build behavior in book.toml, use a discovered configuration file, or run the standalone CLI with explicit flags in CI.

Common workflows

Strict CI and informational local builds

Keep the preprocessor informational for local builds:

[preprocessor.lint]
fail-on-warnings = false

Run a separate strict lint step in CI:

mdbook-lint lint --config .mdbook-lint.toml --fail-on-warnings src/
mdbook build

This avoids relying on an environment-variable override and gives CI direct control over paths and output format.

Progressive adoption

Start with the maintained low-noise preset:

[preprocessor.lint]
preset = "baseline"

Inspect the exact list with mdbook-lint rules --preset baseline. Remove preset when the book is ready to use the complete stable default rule set.

Rule-specific configuration

Keep rule behavior in .mdbook-lint.toml:

[MD003]
style = "atx"

[MD013]
line_length = 100
code_blocks = false

[MD033]
allowed_elements = ["details", "summary"]

Validate the file before building:

mdbook-lint check .mdbook-lint.toml

GitHub workflows

The most predictable CI setup runs the CLI explicitly and then builds the book:

name: Documentation

on:
  push:
  pull_request:

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable

      - name: Install documentation tools
        run: |
          cargo install mdbook
          cargo install mdbook-lint

      - name: Validate lint configuration
        run: mdbook-lint check .mdbook-lint.toml

      - name: Lint documentation
        run: mdbook-lint lint --fail-on-warnings --output github src/

      - name: Build documentation
        run: mdbook build

Use --config <FILE> on the lint command if the configuration is not named for automatic discovery.

Limitations

• Preprocessor mode checks every chapter mdBook supplies. It does not support include or exclude chapter globs.
• Inline HTML comments cannot enable or disable rules for a portion of a file.
• Preprocessor diagnostics do not have selectable concise, detailed, or JSON formats. The standalone lint command supports default, json, and github output.
• mdbook-lint does not consume RUST_LOG; use --verbose with standalone CLI commands and mdbook build -v for mdBook diagnostics.

Troubleshooting

If the preprocessor does not run, first check that both executables are on PATH and that book.toml contains [preprocessor.lint]:

command -v mdbook
command -v mdbook-lint
mdbook build -v

For configuration problems, validate the external file and compare standalone behavior:

mdbook-lint check .mdbook-lint.toml
mdbook-lint --verbose lint --config .mdbook-lint.toml src/

See the Troubleshooting Guide for more diagnostic steps.

Next steps

• Configuration
• CLI Usage
• CI vs Preprocessor
• Troubleshooting

CI vs Preprocessor: Choosing Your Integration Strategy

This guide helps you choose between running mdbook-lint as an mdBook preprocessor or as a standalone CLI tool in CI, and explains why you typically want one approach but not both.

TL;DR Recommendation

For CI/CD pipelines: Use the standalone CLI. For local development: Use the preprocessor (optional).

The standalone CLI gives you more control, better error handling, and avoids configuration discovery issues that can occur in preprocessor mode.

Quick Decision Guide

Integration Approaches

Approach 1: mdBook Preprocessor (Best for Local Development)

When to use:

• You want automatic linting during mdbook serve
• You prefer configuration in book.toml
• You want immediate feedback while writing

When NOT to use:

• In CI/CD pipelines (use standalone CLI instead)
• When you need precise control over exit codes
• When you need detailed error output for debugging

Setup in book.toml:

[preprocessor.lint]
fail-on-warnings = false  # Set to true for strict mode
disabled-rules = ["MD013", "MD033"]

[MD007]
indent = 4

In CI (GitHub Actions):

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install mdBook and mdbook-lint

        run: |

          cargo install mdbook
          cargo install mdbook-lint
      - name: Build book (linting happens automatically)
        run: mdbook build
        env:
# Optional: Override settings for CI

          MDBOOK_PREPROCESSOR__MDBOOK_LINT__FAIL_ON_WARNINGS: true

Advantages:

• Linting happens automatically during mdbook serve
• Immediate feedback while writing documentation
• Works seamlessly with local mdBook workflow

Disadvantages:

• Configuration discovery can be tricky in CI environments
• Limited control over error handling and exit codes
• No SARIF output for GitHub Security tab
• Errors appear inline with mdBook build output
• Can't fail fast in CI (must start book build first)

Approach 2: Standalone CLI (Recommended for CI/CD)

When to use:

• CI/CD pipelines (recommended for all CI use cases)
• You want to fail fast before other expensive operations
• You need clear, actionable error output
• You need SARIF output for GitHub Security integration
• You don't use mdBook (just markdown files)

Setup with .mdbook-lint.toml:

# Start existing documentation with the low-noise baseline.
preset = "baseline"
fail-on-warnings = true

Inspect the exact selection with mdbook-lint rules --preset baseline. Remove the preset line when the project is ready to adopt the complete stable ruleset. Project-specific exclusions can be added with disabled-rules.

In CI (GitHub Actions):

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
# Option A: Using GitHub Action

      - name: Lint Markdown
        uses: joshrotenberg/mdbook-lint-action@v1
        with:
          files: 'docs/**/*.md'
          format: sarif
          output-file: results.sarif
      
# Option B: Direct installation

      - name: Install and run mdbook-lint

        run: |

          cargo install mdbook-lint
          mdbook-lint lint docs/ --preset baseline --fail-on-warnings
      
# Optional: Upload SARIF results

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

SARIF output

The CLI emits SARIF v2.1.0 directly:

mdbook-lint lint docs/ --output sarif --output-file results.sarif

--output-file writes the report to disk and leaves stdout clean, so normal diagnostics and the process exit status are unaffected. The report is written even when the run fails, which is what a code-scanning upload step needs:

      - name: Lint Markdown
        run: mdbook-lint lint docs/ --output sarif --output-file results.sarif
        continue-on-error: true

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

A clean run still produces a valid report with an empty results array, so the upload step does not need to special-case it.

Each result carries the rule ID, a severity mapped to the SARIF levels (error, warning, note), and a 1-based line and column. Rule descriptors are derived from rule metadata and link to the published rule reference. Results are sorted by location, so repeated runs over unchanged input produce identical reports.

Advantages:

• Fails fast in CI pipeline before expensive build steps
• Clear, standalone error output for debugging
• SARIF output for GitHub Security tab
• Full control over when and how linting runs
• Can run in parallel with other checks
• Works with or without mdBook
• Supports smart CLI detection (e.g., mdbook-lint docs/)

Disadvantages:

• No automatic linting during local mdbook serve
• Requires explicit invocation in CI workflow
• Consider adding preprocessor for local development feedback

Why Not Both

Running mdbook-lint both as a preprocessor AND standalone in CI is usually redundant and can cause problems:

Problems with Running Both

1. Duplicate Work: The same files get linted twice, wasting CI time
2. Configuration Drift: Two places to maintain rules can lead to inconsistencies
3. Confusing Failures: Issues might be reported twice in different formats
4. Maintenance Burden: Updates need to be synchronized in multiple places

Valid Exception: Different Rule Sets

The only scenario where using both makes sense is when you intentionally want different rules:

# CI: Strict linting before build
- name: Strict lint check
  run: mdbook-lint lint docs/ --config .mdbook-lint.strict.toml

# Build: Lenient linting during build
- name: Build with lenient linting
  run: mdbook build  # Uses preprocessor with book.toml config

Migration Strategies

From Preprocessor to Standalone CI

If you're currently using the preprocessor but want to switch to standalone CI:

1. Extract configuration from book.toml to .mdbook-lint.toml
2. Remove preprocessor section from book.toml
3. Update CI to run mdbook-lint before mdbook build
4. Document the change for your team

From Standalone to Preprocessor

If you're using standalone but want to switch to preprocessor:

1. Add preprocessor section to book.toml
2. Copy configuration from .mdbook-lint.toml to book.toml
3. Remove standalone lint step from CI
4. Update documentation for developers

Recommended Configurations

For CI/CD: Use Standalone CLI (Recommended)

# .github/workflows/docs.yml
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install mdbook-lint
        run: cargo install mdbook-lint
      - name: Lint documentation
        run: mdbook-lint docs/src/ --preset baseline --fail-on-warnings

For Local Development: Add Preprocessor (Optional)

# book.toml - for local development feedback only
[preprocessor.lint]
fail-on-warnings = false

Combined Setup (Best of Both Worlds)

Use standalone CLI in CI for control and reliability, with optional preprocessor for local development:

# .github/workflows/docs.yml - CI uses standalone
- name: Lint documentation
  run: mdbook-lint docs/src/ --preset baseline --fail-on-warnings
- name: Build book
  run: mdbook build docs/

# book.toml - local development uses preprocessor (optional)
[preprocessor.lint]
fail-on-warnings = false

This approach gives you:

• Reliable CI with clear error output
• Fast feedback during local mdbook serve
• No duplicate configuration (use .mdbook-lint.toml for both)

Common Pitfalls to Avoid

1. Don't duplicate the same rules in both preprocessor and standalone configs

2. Don't run both in CI unless you have a specific reason

3. Don't use || true to ignore failures - fix the issues or disable specific rules

4. Don't forget to document which approach you're using for new contributors

Summary

• Use standalone CLI in CI: Better control, clearer errors, fail-fast capability
• Use preprocessor for local development: Optional, provides feedback during mdbook serve
• Avoid using both in CI: Redundant and can cause confusion
• Share configuration: Use .mdbook-lint.toml which works for both modes
• Be consistent: Document your choice and stick with it across your project

Compatibility

mdbook-lint is designed to work seamlessly across different versions of mdBook and various environments.

mdBook Version Support

mdbook-lint supports both mdBook 0.4.x and 0.5.x series.

Supported Versions

Automatic Version Detection

When running as an mdBook preprocessor, mdbook-lint automatically detects the mdBook version and handles protocol differences transparently. You don't need to configure anything differently based on your mdBook version.

mdBook 0.5.x Changes

mdBook 0.5.0 introduced breaking changes to the preprocessor JSON protocol:

• The sections field was renamed to items in book chapter structures
• The __non_exhaustive marker field was removed

mdbook-lint automatically normalizes these differences, so your configuration and usage remain the same regardless of which mdBook version you use.

Platform Support

mdbook-lint provides prebuilt binaries for all major platforms:

Minimum Rust Version

If building from source, mdbook-lint requires:

• Rust Edition: 2024
• Minimum Supported Rust Version (MSRV): 1.85.0

Configuration Compatibility

markdownlint Compatibility

mdbook-lint aims for compatibility with markdownlint rule definitions. Standard rules (MD001-MD060) follow the same semantics as markdownlint where applicable.

Configuration differences:

• mdbook-lint uses TOML configuration by default (.mdbook-lint.toml)
• YAML and JSON configuration formats are also supported
• Rule configuration options may have slightly different names

CI Environment Support

mdbook-lint works in all major CI environments:

• GitHub Actions
• GitLab CI
• CircleCI
• Jenkins
• Azure Pipelines

See CI vs Preprocessor for guidance on choosing the right integration approach.

Continuous Compatibility Testing

mdbook-lint runs automated compatibility tests against multiple mdBook versions on a weekly schedule. These tests verify that the preprocessor integration works correctly across all supported mdBook versions.

You can view the test results in the mdBook Compatibility workflow on GitHub.

Reporting Compatibility Issues

If you encounter compatibility issues with a specific mdBook version or platform, please open an issue with:

1. Your mdBook version (mdbook --version)
2. Your mdbook-lint version (mdbook-lint --version)
3. Your operating system and architecture
4. The error message or unexpected behavior
5. A minimal example that reproduces the issue

Troubleshooting Guide

This guide covers common installation, configuration, preprocessor, rule, and CI problems. Commands and configuration examples match the current mdbook-lint CLI.

Installation

Command Not Found

Confirm whether the executable is on PATH:

command -v mdbook-lint
mdbook-lint --version

For a Cargo installation, the executable normally lives in ~/.cargo/bin:

cargo install mdbook-lint --force
export PATH="$HOME/.cargo/bin:$PATH"

If mdBook runs in CI or a container, install mdbook-lint in that environment as well. Installing it on the host does not make it available inside a container.

Installation from Source Fails

Update the stable Rust toolchain and retry with locked dependencies:

rustup update stable
cargo install mdbook-lint --locked --force

Include the Rust version and the complete Cargo error when reporting a build failure:

rustc --version
cargo --version

Configuration

Configuration Is Not Loading

Validate the file directly:

mdbook-lint check .mdbook-lint.toml

Then run linting with an explicit path and verbose status output:

mdbook-lint --verbose lint --config .mdbook-lint.toml src/

Without --config, mdbook-lint searches the current directory and its parents. At each directory it checks these names in order:

1. .mdbook-lint.toml
2. mdbook-lint.toml
3. .mdbook-lint.yaml
4. .mdbook-lint.yml
5. .mdbook-lint.json

The verbose command prints the selected configuration path. A similarly named file outside the search path is not loaded.

Rule Configuration Is Ignored

Rule-specific configuration uses a top-level table named after the rule:

[MD013]
line_length = 100
code_blocks = false

[MD024]
siblings_only = true

Do not nest rule configuration under [core], [rules.config], or [preprocessor.lint.rules]. Those tables are not part of the configuration schema.

Start from the generated reference when you are unsure which options a rule accepts:

mdbook-lint init --include-all --output reference.toml
mdbook-lint rules --detailed

Configuration in book.toml Is Ignored

The mdBook preprocessor reads only these settings from [preprocessor.lint]:

• preset
• fail-on-warnings
• fail-on-errors
• enabled-rules
• disabled-rules
• enabled-categories
• disabled-categories

For rule-specific settings and other global options, create a discovered .mdbook-lint.toml file in the book root or a parent directory.

For example:

# book.toml
[preprocessor.lint]
preset = "baseline"
fail-on-warnings = true
disabled-rules = ["MD014"]

# .mdbook-lint.toml
[MD013]
line_length = 100

Environment Variables Have No Effect

mdbook-lint does not implement environment-variable configuration overrides. Names such as MDBOOK_PREPROCESSOR__..., MDBOOK_LINT_CONFIG, and RUST_LOG are not read by the application.

Use one of the supported mechanisms instead:

• a discovered configuration file;
• supported [preprocessor.lint] keys in book.toml;
• --config, --fail-on-warnings, --enable, or --disable with the standalone CLI.

Preprocessor Issues

The Preprocessor Does Not Run

Check the executables and the mdBook configuration:

command -v mdbook
command -v mdbook-lint
grep -n "preprocessor.lint" book.toml
mdbook build -v

A minimal book.toml entry is:

[preprocessor.lint]

If command discovery is unusual in your environment, set it explicitly:

[preprocessor.lint]
command = "mdbook-lint"

The Build Fails Unexpectedly

Warnings fail the build only when fail-on-warnings = true. Errors fail by default. Run the linter directly to see the same diagnostics without mdBook's output around them:

mdbook-lint lint src/

To check whether build policy is the cause, inspect book.toml and the discovered configuration file for:

fail-on-warnings = true
fail-on-errors = true

Set RUST_BACKTRACE=1 only when diagnosing a panic. It does not enable normal application logging.

Another Preprocessor Appears to Conflict

mdbook-lint does not modify chapter content, so content-order conflicts are unusual. Temporarily remove other preprocessor tables from a copy of book.toml, rebuild, and add them back one at a time to identify the source.

Do not rely on mdbook-lint-specific before or after keys; mdbook-lint does not read or enforce them.

Rule Behavior

A Rule Reports a False Positive

First reproduce the result with only that rule enabled:

mdbook-lint lint --enable MD033 path/to/file.md

If the rule has supported options, configure its top-level table:

[MD033]
allowed_elements = ["details", "summary"]

Otherwise disable it globally or for that command:

disabled-rules = ["MD033"]

mdbook-lint lint --disable MD033 src/

Inline mdbook-lint-disable HTML comments are not implemented. If a rule needs per-file or inline suppression, open a feature request separately from the false-positive report.

When reporting a bug, include the smallest input that reproduces it, the rule ID, the exact command, and mdbook-lint --version.

Rules Appear to Conflict

Run each rule independently to identify which diagnostics and fixes overlap:

mdbook-lint lint --enable MD018 path/to/file.md
mdbook-lint lint --enable MD020 path/to/file.md

Preview automatic fixes before applying them:

mdbook-lint lint --fix --dry-run path/to/file.md

If two automatic fixes conflict, report both rule IDs and the original input.

Performance

Compare build time with and without the preprocessor enabled in a temporary copy of book.toml:

time mdbook build

Then select the maintained baseline rather than adding unsupported chapter globs:

[preprocessor.lint]
preset = "baseline"

Preprocessor mode checks the chapters supplied by mdBook and does not implement include or exclude patterns. If path-level filtering is required, run the standalone CLI on explicit paths and use ignore-paths in .mdbook-lint.toml.

CI

CI Differs from Local Results

Print tool versions and validate the same configuration used locally:

mdbook --version
mdbook-lint --version
mdbook-lint check .mdbook-lint.toml
mdbook-lint lint --config .mdbook-lint.toml --fail-on-warnings src/

Pinning versions in CI avoids changes caused by installing different releases on different runs.

For GitHub Actions annotations, use the standalone output format:

mdbook-lint lint --output github --fail-on-warnings src/

Preprocessor output does not have a configurable JSON or GitHub format.

Useful Diagnostics

Use the CLI's supported status and output options:

mdbook-lint --verbose lint src/
mdbook-lint lint --output json src/
mdbook-lint lint --color never src/
mdbook build -v

List rules and inspect configuration separately:

mdbook-lint rules --detailed
mdbook-lint check .mdbook-lint.toml

Getting Help

Search or open an issue at https://github.com/joshrotenberg/mdbook-lint/issues. Include:

• mdbook-lint --version;
• mdbook --version when preprocessor mode is involved;
• the relevant configuration with secrets removed;
• the smallest input that reproduces the problem;
• the exact command and complete diagnostic output.

For configuration syntax, also see Configuration. For preprocessor setup, see mdBook Integration.

Rules Reference

mdbook-lint provides comprehensive markdown linting with three rule categories.

Standard Markdown Rules

59 rules (MD001-MD059) based on the widely-used markdownlint specification. These rules ensure consistent markdown formatting and style.

Categories

• Heading Rules - Heading hierarchy and formatting
• List Rules - List formatting and consistency
• Whitespace Rules - Trailing spaces, blank lines
• Link Rules - URL formatting and link text
• Code Rules - Code block formatting and fencing
• Style Rules - Emphasis and formatting consistency

mdBook-Specific Rules

Rules specifically designed for mdBook projects, validating mdBook-specific syntax and conventions.

Rules

• MDBOOK001 - Code blocks should have language tags
• MDBOOK002 - SUMMARY.md structure validation
• MDBOOK003 - Internal link validation
• MDBOOK004 - Part title formatting
• MDBOOK005 - Chapter path validation
• MDBOOK006 - Draft chapter validation
• MDBOOK007 - Separator syntax validation

ADR Rules

17 rules (ADR001-ADR017) for validating Architecture Decision Records against Nygard and MADR 4.0 formats.

Categories

• Structure Rules (ADR001-ADR006) - Title, status, date, required sections
• Validation Rules (ADR007-ADR009) - Status values, date format, filename
• Collection Rules (ADR010-ADR013) - Multi-document analysis
• Content Quality Rules (ADR014-ADR017) - Meaningful content validation

Quick Reference

Rules with Automatic Fix Support

The following rules can automatically fix violations:

• MD009 - Remove trailing spaces
• MD010 - Replace hard tabs with spaces
• MD012 - Remove multiple consecutive blank lines
• MD018 - Add space after hash in ATX headings
• MD019 - Fix multiple spaces after hash
• MD020 - Add missing spaces inside closed ATX headings
• MD021 - Fix multiple spaces inside closed ATX headings
• MD023 - Remove indentation from headings
• MD027 - Fix multiple spaces after blockquote symbol
• MD030 - Fix spaces after list markers
• MD034 - Wrap bare URLs in angle brackets
• MD047 - Ensure files end with single newline

Disabling Rules

Rules can be disabled globally or for specific files:

# Disable globally
[rules]
MD002 = false
MD041 = false

# Disable for specific files
[ignore]
MD013 = ["CHANGELOG.md", "docs/api/*.md"]

Standard Markdown Rules

mdbook-lint implements 59 standard markdown linting rules based on the markdownlint specification. These rules help maintain consistent, readable, and properly formatted markdown documentation.

Rule Categories

Heading Rules

Rules for heading hierarchy, formatting, and style consistency.

List Rules

Rules for list formatting, indentation, and marker consistency.

Whitespace Rules

Rules for managing spaces, tabs, and blank lines.

Link Rules

Rules for URL formatting, link text, and reference links.

Code Rules

Rules for code blocks, inline code, and fencing style.

Emphasis Rules

Rules for bold, italic, and other emphasis formatting.

Complete Rule List

Legend:

• ✅ Automatic fix available
• ❌ Manual fix required

Heading Rules

Heading rules ensure proper document structure, hierarchy, and formatting for markdown headings.

Rules in This Category

Best Practices

Document Structure

A well-structured document follows these heading principles:

1. Start with H1: Documents should begin with a single H1 heading
2. Sequential Levels: Never skip heading levels (H1 → H3 is wrong)
3. Logical Hierarchy: Use headings to create a document outline
4. Consistent Style: Use either ATX (#) or Setext style consistently

ATX vs Setext Headings

ATX Style (Recommended):

# Heading 1
## Heading 2
### Heading 3

Setext Style (Limited to H1 and H2):

Heading 1
=========

Heading 2
---------

Closed ATX Headings

Some prefer closed ATX headings for symmetry:

#Heading 1#


##Heading 2##


###Heading 3###

Rules MD020 and MD021 ensure proper formatting of closed headings.

Common Issues and Solutions

Issue: Inconsistent Heading Hierarchy

Problem: Jumping between heading levels disrupts document flow.

# Main Title
### Subsection (skips H2)
## Back to H2
##### Deep section (skips H3 and H4)

Solution: Maintain sequential heading levels.

# Main Title
## Section
### Subsection
## Another Section
### Subsection
#### Deeper Content
##### Deepest Content

Issue: Multiple H1 Headings

Problem: Multiple top-level headings confuse document structure.

# First Title
Content...
# Second Title
More content...

Solution: Use a single H1 with H2s for major sections.

# Document Title
## First Section
Content...
## Second Section
More content...

Issue: Indented Headings

Problem: Headings with leading spaces may not render correctly.

    # This might not be a heading
  ## This is problematic

Solution: Start headings at the beginning of the line.

# Proper Heading
## Another Proper Heading

Accessibility Considerations

Proper heading structure is crucial for accessibility:

• Screen Readers: Use headings to navigate and understand document structure
• Keyboard Navigation: Many tools allow jumping between headings
• Document Outline: Assistive technologies generate outlines from headings
• WCAG Compliance: Proper heading hierarchy is part of WCAG 2.1 guidelines

Integration with mdBook

mdBook relies heavily on proper heading structure:

1. Table of Contents: Generated from heading hierarchy
2. Search Index: Headings are weighted in search results
3. Navigation: Sidebar navigation reflects heading structure
4. Anchors: Automatic anchor generation for deep linking

Configuration Examples

Enforce ATX Style Only

[MD003]
style = "atx"

Allow Trailing Punctuation

[MD026]
enabled = false

Require Document to Start with H1

[MD041]
level = 1
front_matter_title = false

MD001 - Heading Increment

Heading levels should only increment by one level at a time.

This rule is triggered when you skip heading levels in a markdown document. For example, a heading level 1 should be followed by level 2, not level 3.

Why This Rule Exists

Proper heading hierarchy improves document structure, accessibility, and navigation. Screen readers and document outlines rely on sequential heading levels to convey the document's organization to users.

Examples

❌ Incorrect (violates rule)

# Title

### Subsection (skips h2)

## Back to h2

##### Deep section (skips h3 and h4)

✅ Correct

# Title

## Section

### Subsection

#### Subsubsection

##### Deep section

Configuration

This rule has no configuration options. It always enforces strict sequential heading levels.

When to Disable

Consider disabling this rule if:

• You're working with generated content that doesn't follow strict hierarchy
• You're importing documentation from external sources with different conventions
• Your project has specific heading level requirements

Rule Details

• Rule ID: MD001
• Aliases: heading-increment
• Category: Structure
• Severity: Warning
• Automatic Fix: Not available

Common Violations and Solutions

Skipping from H1 to H3

Problem:

# Main Title
### Subsection

Solution:

# Main Title
## Section
### Subsection

Deep Nesting Without Intermediate Levels

Problem:

## Chapter
##### Deep Detail

Solution:

## Chapter
### Section
#### Subsection
##### Deep Detail

Rationale for Sequential Headings

1. Accessibility: Screen readers rely on proper heading hierarchy to help users navigate documents
2. Document Structure: Sequential headings create a logical outline
3. SEO: Search engines use heading structure to understand content hierarchy
4. Table of Contents: Automated TOC generators expect proper nesting

Integration with mdBook

mdBook's sidebar generation relies on proper heading structure. Violating this rule can lead to:

• Broken navigation in the sidebar
• Incorrect TOC generation
• Poor mobile navigation experience

Related Rules

• MD002 - First heading should be a top-level heading
• MD003 - Heading style consistency
• MD022 - Headings should be surrounded by blank lines
• MD025 - Multiple top-level headings in the same document

References

• WCAG 2.1 - Heading Levels
• MDN - Heading Elements
• CommonMark Spec - ATX Headings

MD002 - First Heading H1

First heading should be a top-level heading (H1).

Deprecated: This rule is superseded by MD041 which offers an improved implementation. Consider using MD041 instead.

Why This Rule Exists

Documents should start with a top-level heading (H1) to establish proper hierarchy. This ensures consistent document structure and helps screen readers and document outlines understand the content organization.

Examples

Incorrect

## Introduction

This document starts with an H2.

Correct

# Document Title

## Introduction

The document properly starts with an H1.

Configuration

[MD002]
level = 1  # Expected first heading level (default: 1)

When to Disable

• When using MD041 instead (recommended)
• Documents that are fragments or partials
• Auto-generated content with different conventions

Rule Details

• Rule ID: MD002
• Aliases: first-heading-h1
• Category: Structure
• Severity: Warning
• Auto-fix: Yes (can add H1 if missing)
• Deprecated: Yes (use MD041)

Related Rules

• MD001 - Heading increment
• MD041 - First line should be a top-level heading (replacement)
• MD025 - Single top-level heading

MD003 - Heading Style

Heading style should be consistent throughout the document.

Why This Rule Exists

Markdown supports multiple heading styles. Mixing styles within a document creates visual inconsistency and can confuse readers and tooling.

Heading Styles

ATX Style (Recommended)

# Heading 1
## Heading 2
### Heading 3

ATX Closed Style

#Heading 1#

##Heading 2##

###Heading 3###

Setext Style (H1 and H2 only)

Heading 1
=========

Heading 2
---------

Examples

Incorrect

# ATX Heading

Setext Heading
--------------

### Another ATX

Correct

# Main Title

## Section One

### Subsection

Configuration

[MD003]
style = "atx"  # Options: "atx", "atx_closed", "setext", "consistent"

When to Disable

• Working with legacy documents using mixed styles
• Importing content from multiple sources

Rule Details

• Rule ID: MD003
• Aliases: heading-style
• Category: Structure
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD001 - Heading increment
• MD018 - Space after hash in ATX headings
• MD019 - Multiple spaces after hash

MD018 - No Space After Hash on ATX Style Heading

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures there's a space after the hash character(s) in ATX-style headings. The space improves readability and is required by many markdown parsers.

Why This Rule Exists

A space after the hash is important because:

• Many markdown parsers require it for proper heading recognition
• Improves readability and consistency
• Follows CommonMark specification
• Prevents confusion with other hash-prefixed content

Examples

❌ Incorrect (violates rule)

# Heading without space

## Another heading missing space

### Third level also needs space

✅ Correct

# Heading with proper space
## Another heading correctly formatted
### Third level with space

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Add a single space after the hash character(s)
• Preserve the heading level and content
• Handle all heading levels (1-6)

Apply Fix

# Fix heading spacing issues
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• You're working with a non-standard markdown parser that doesn't require spaces
• Your content includes hash-prefixed text that isn't meant to be headings

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD018"]

Disable Inline

<!-- mdbook-lint-disable MD018 -->
# NoSpaceHeading

<!-- mdbook-lint-enable MD018 -->

Related Rules

• MD019 - Multiple spaces after hash on ATX heading
• MD020 - Missing space inside hashes on closed ATX heading
• MD021 - Multiple spaces inside hashes on closed ATX heading
• MD022 - Headings should be surrounded by blank lines
• MD023 - Headings must start at the beginning of the line

References

• Original markdownlint rule
• CommonMark Specification - ATX Headings

MD019 - Multiple Spaces After Hash on ATX Style Heading

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures there's only a single space after the hash character(s) in ATX-style headings. Multiple spaces are unnecessary and can cause inconsistent formatting.

Why This Rule Exists

Single space after hash is important because:

• Maintains consistent formatting across documents
• Follows standard markdown conventions
• Reduces unnecessary whitespace
• Improves readability and predictability

Examples

❌ Incorrect (violates rule)

# Heading with multiple spaces

## Another heading with extra spaces

### Too many spaces here

✅ Correct

# Heading with single space
## Another heading correctly formatted
### Proper spacing

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Reduce multiple spaces to a single space after hash character(s)
• Preserve the heading level and content
• Handle all heading levels (1-6)

Apply Fix

# Fix multiple space issues in headings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your style guide requires multiple spaces for alignment
• You're maintaining legacy content with specific spacing requirements

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD019"]

Disable Inline

<!-- mdbook-lint-disable MD019 -->
## Heading with multiple spaces allowed

<!-- mdbook-lint-enable MD019 -->

Related Rules

• MD018 - No space after hash on ATX heading
• MD020 - Missing space inside hashes on closed ATX heading
• MD021 - Multiple spaces inside hashes on closed ATX heading
• MD022 - Headings should be surrounded by blank lines
• MD023 - Headings must start at the beginning of the line

References

• Original markdownlint rule
• CommonMark Specification - ATX Headings

MD020 - Missing Space Inside Hashes on Closed ATX Style Headings

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule checks heading-like closed ATX syntax for missing separators between the heading text and its opening or closing hash sequence. A closed ATX heading uses spaces or tabs inside both sets of hashes.

Per CommonMark, a trailing hash sequence is a closing delimiter only when it is preceded by a space or tab. Content-adjacent hashes in headings such as C# and F# are ordinary heading text and do not trigger this rule.

Examples

❌ Incorrect

#Heading 1#
##Heading 2 ##

✅ Correct

# Heading 1 #
## Heading 2 ##

# Open headings are also valid
### C#
### F#

### Heading# is an open ATX heading whose text ends in #. MD020 does not guess that the final hash was intended as a closing delimiter.

Configuration

This rule has no configuration options.

Automatic Fix

The fix adds missing separators where closed-heading intent is unambiguous:

##Heading##  ->  ## Heading ##
##Heading ## ->  ## Heading ##

Content-adjacent hashes are never removed or converted into delimiters.

# Apply fixes
mdbook-lint lint --fix docs/

# Preview fixes
mdbook-lint lint --fix --dry-run docs/

Related Rules

• MD003 - Heading style
• MD018 - Missing space after hashes on ATX headings
• MD019 - Multiple spaces after hashes on ATX headings
• MD021 - Multiple spaces inside closed ATX headings

References

• Original markdownlint rule
• CommonMark Specification - ATX Headings

MD021 - Multiple Spaces Inside Hashes on Closed ATX Style Heading

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures closed ATX-style headings have only a single space inside the hash markers. Multiple spaces create inconsistent formatting and unnecessary whitespace.

Why This Rule Exists

Single space inside closed headings is important because:

• Maintains consistent formatting
• Follows standard markdown conventions
• Improves readability
• Ensures proper rendering across different parsers

Examples

❌ Incorrect (violates rule)

#Heading with multiple spaces#


##Another heading##


###Too many internal spaces###

✅ Correct

#Heading with single spaces#


##Another heading##


###Properly spaced heading###


# Open heading is also fine

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Reduce multiple spaces to single spaces inside hash markers
• Preserve the heading level and content
• Maintain the closed heading style

Apply Fix

# Fix multiple spaces in closed headings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your style guide requires multiple spaces for alignment
• You prefer open ATX headings (without closing hashes)

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD021"]

Disable Inline

<!-- mdbook-lint-disable MD021 -->
##Heading with multiple spaces##


<!-- mdbook-lint-enable MD021 -->

Related Rules

• MD018 - No space after hash on ATX heading
• MD019 - Multiple spaces after hash on ATX heading
• MD020 - Missing space inside hashes on closed ATX heading
• MD022 - Headings should be surrounded by blank lines
• MD003 - Heading style

References

• Original markdownlint rule
• CommonMark Specification - ATX Headings

MD022 - Blanks Around Headings

Headings should be surrounded by blank lines.

Why This Rule Exists

Blank lines around headings improve readability and ensure consistent rendering across Markdown parsers. Some parsers require blank lines to properly recognize headings.

Examples

Incorrect

Some paragraph text.
## Heading
More text here.

Correct

Some paragraph text.

## Heading

More text here.

Configuration

[MD022]
lines_above = 1  # Blank lines before heading (default: 1)
lines_below = 1  # Blank lines after heading (default: 1)

When to Disable

• Documents with compact formatting requirements
• Content where headings immediately follow other headings

Rule Details

• Rule ID: MD022
• Aliases: blanks-around-headings
• Category: Structure
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD023 - Headings start at beginning of line
• MD031 - Blanks around fenced code blocks
• MD032 - Blanks around lists

MD023 - Headings Must Start at the Beginning of the Line

Severity: Warning
Category: Headings
Auto-fix: ✓ Available

Rule Description

This rule ensures headings start at the beginning of the line without any leading spaces or tabs. Indented headings are not valid in standard markdown.

Why This Rule Exists

Headings at line start are important because:

• Indented text with hashes may be interpreted as code or regular text
• Ensures headings are properly recognized by all parsers
• Maintains consistent document structure
• Follows CommonMark specification

Examples

❌ Incorrect (violates rule)

  # Indented heading
    ## Another indented heading
    ### Tab-indented heading

✅ Correct

# Heading at line start
## Another proper heading
### Correctly positioned heading

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Remove all leading whitespace (spaces and tabs) before headings
• Preserve the heading level and content
• Maintain proper heading structure

Apply Fix

# Fix indented headings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• You're documenting markdown syntax and showing indented hash examples
• Your content includes code blocks with hash-prefixed comments

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD023"]

Disable Inline

<!-- mdbook-lint-disable MD023 -->
    # This indented text is intentional
<!-- mdbook-lint-enable MD023 -->

Related Rules

• MD018 - No space after hash on ATX heading
• MD019 - Multiple spaces after hash on ATX heading
• MD022 - Headings should be surrounded by blank lines
• MD025 - Multiple top-level headings in the same document
• MD026 - Trailing punctuation in heading

References

• Original markdownlint rule
• CommonMark Specification - ATX Headings

MD024 - No Duplicate Headings

Multiple headings with the same content.

Why This Rule Exists

Duplicate headings can confuse readers and break anchor links. Each heading generates a URL fragment, and duplicates create ambiguous navigation targets.

Examples

Incorrect

# Guide

## Introduction

Some content.

## Introduction

More content with same heading.

Correct

# Guide

## Introduction

Some content.

## Getting Started

Different heading for different section.

Siblings Only Mode

With siblings_only: true, duplicates are allowed in different sections:

# Chapter 1

## Summary

Chapter 1 summary.

# Chapter 2

## Summary

Chapter 2 summary (allowed - different parent).

Configuration

[MD024]
siblings_only = false  # Only check sibling headings (default: false)
allow_different_nesting = false  # Allow same text at different levels

When to Disable

• Documents with intentionally repeated section names
• Auto-generated content with structured repetition

Rule Details

• Rule ID: MD024
• Aliases: no-duplicate-heading
• Category: Content
• Severity: Warning
• Auto-fix: No

Related Rules

• MD025 - Single top-level heading
• MD051 - Link fragments validation

MD025 - Single Top-Level Heading

Multiple top-level headings in the same document.

Why This Rule Exists

A document should have a single H1 heading that serves as its title. Multiple H1 headings suggest the content should be split into separate documents or the heading hierarchy needs adjustment.

Examples

Incorrect

# First Title

Content here.

# Second Title

More content.

Correct

# Document Title

## First Section

Content here.

## Second Section

More content.

Configuration

[MD025]
level = 1        # Heading level to check (default: 1)
front_matter_title = ""  # Regex for front matter title

When to Disable

• SUMMARY.md files in mdBook (use MDBOOK025 instead)
• Documents intentionally containing multiple articles
• Changelog files with version headings as H1

Rule Details

• Rule ID: MD025
• Aliases: single-title, single-h1
• Category: Structure
• Severity: Warning
• Auto-fix: No

mdBook Integration

For SUMMARY.md files, this rule is automatically relaxed. Use MDBOOK025 which understands mdBook's multi-section SUMMARY format.

Related Rules

• MD001 - Heading increment
• MD002 - First heading H1
• MD041 - First line top-level heading
• MDBOOK025 - SUMMARY.md heading structure

MD026 - No Trailing Punctuation

Trailing punctuation in headings.

Why This Rule Exists

Headings typically don't end with punctuation like periods or commas. Trailing punctuation can look awkward in tables of contents and navigation menus.

Examples

Incorrect

# Welcome to the Guide.

## Getting Started:

### What is Markdown?

Correct

# Welcome to the Guide

## Getting Started

### What is Markdown

Questions (Configurable)

## Frequently Asked Questions

### How do I install it?

Configuration

[MD026]
punctuation = ".,;:!?"  # Characters to flag (default: ".,;:!")

The ? is excluded by default to allow question headings in FAQ sections.

When to Disable

• Documents with headings that are complete sentences
• Stylistic choice to include punctuation
• FAQ sections with question marks (or adjust punctuation config)

Rule Details

• Rule ID: MD026
• Aliases: no-trailing-punctuation
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes (removes trailing punctuation)

Related Rules

• MD018 - Space after hash
• MD021 - Spaces in closed ATX headings

MD041 - First Line Top-Level Heading

First line in a file should be a top-level heading.

Why This Rule Exists

Documents should start with a title heading to establish context. This helps with document navigation, accessibility, and table of contents generation.

Examples

Incorrect

Some introductory text before the heading.

# Document Title

Content here.

Correct

# Document Title

Some introductory text.

Content here.

With Front Matter

---
title: My Document
---

# Document Title

Content here.

Configuration

[MD041]
level = 1              # Expected heading level (default: 1)
front_matter_title = "^\\s*title\\s*[:=]"  # Regex for front matter title

If front_matter_title matches, the document is considered to have a title and the rule passes.

When to Disable

• Fragment documents included in larger documents
• Files with front matter providing the title
• Auto-generated content with different structure

Rule Details

• Rule ID: MD041
• Aliases: first-line-heading, first-line-h1
• Category: Structure
• Severity: Warning
• Auto-fix: No

Replaces MD002

This rule supersedes MD002 with improved handling of front matter and more configuration options.

Related Rules

• MD001 - Heading increment
• MD002 - First heading H1 (deprecated)
• MD025 - Single top-level heading

List Rules

List rules ensure consistent formatting, indentation, and structure for both ordered and unordered lists.

Rules in This Category

List Basics

Unordered Lists

Markdown supports three markers for unordered lists:

* Item with asterisk
- Item with dash
+ Item with plus

All render the same, but consistency is important.

Ordered Lists

1. First item
2. Second item
3. Third item

Or with lazy numbering:

1. First item
1. Second item
1. Third item

Best Practices

Consistent Markers

Pick one unordered list marker and stick with it:

Good:

* First item
* Second item
  * Nested item
  * Another nested
* Third item

Bad:

* First item
- Second item
  + Nested item
  * Another nested
+ Third item

Proper Indentation

Use consistent indentation for nested lists:

2-space indentation:

* Parent item
  * Child item
    * Grandchild item
  * Another child
* Another parent

4-space indentation:

* Parent item
    * Child item
        * Grandchild item
    * Another child
* Another parent

Spacing After Markers

Maintain consistent spacing after list markers:

Good (single space):

* Item one
* Item two
1. First item
2. Second item

Bad (inconsistent):

*Item one
*  Item two
1.First item
2.  Second item

Complex List Structures

Multi-line List Items

For list items with multiple paragraphs:

1. First item with multiple paragraphs.

   This is still part of the first item. Note the blank line above
   and the indentation.

2. Second item.

   * Nested list in second item
   * Another nested item

3. Third item.

Lists with Code Blocks

Proper indentation for code blocks in lists:

1. Install the package:

   ```bash
   npm install mdbook-lint

1. Configure the linter:

   {
     "rules": {
       "MD009": true
     }
   }
   

2. Run the linter.

### Task Lists

GitHub Flavored Markdown task lists:

```markdown
- [x] Completed task
- [ ] Incomplete task
- [ ] Another todo
  - [x] Completed subtask
  - [ ] Incomplete subtask

Common Issues and Solutions

Issue: Inconsistent List Indentation

Problem:

* Item 1
  * Nested with 2 spaces
    * Deep nested with 4 spaces
 * Wrong indentation
   * More inconsistency

Solution:

* Item 1
  * Nested with 2 spaces
  * Consistent 2-space indent
  * All items aligned
    * Deeper nesting maintains pattern

Issue: Missing Blank Lines Around Lists

Problem:

Some paragraph text
* List starts immediately
* No separation
Paragraph continues here

Solution:

Some paragraph text

* List has blank line before
* Proper separation

Paragraph has blank line after list

Issue: Lazy Numbering Problems

Problem with lazy numbering:

1. First item
1. Second item
5. Oops, wrong number
1. Fourth item

Solution 1 (sequential):

1. First item
2. Second item
3. Third item
4. Fourth item

Solution 2 (all ones):

1. First item
1. Second item
1. Third item
1. Fourth item

Accessibility Considerations

Proper list formatting improves accessibility:

1. Screen Readers: Announce list structure and item count
2. Navigation: Users can skip between lists
3. Context: Proper nesting conveys relationships
4. Semantics: Lists convey meaning beyond visual formatting

mdBook-Specific Considerations

In mdBook projects:

1. Table of Contents: Lists in SUMMARY.md define book structure
2. Navigation: Nested lists create hierarchical navigation
3. Rendering: List formatting affects HTML output
4. Search: List items are indexed for search

Configuration Examples

Enforce Consistent Unordered List Style

[MD004]
style = "asterisk"  # or "dash" or "plus"

Set List Indentation

[MD007]
indent = 2  # or 4, or any consistent value

Configure Ordered List Style

[MD029]
style = "ordered"  # or "one" for all 1s

Spaces After List Markers

[MD030]
ul_single = 1  # Spaces after unordered list marker
ol_single = 1  # Spaces after ordered list marker
ul_multi = 1   # Spaces after marker for multi-line items
ol_multi = 1   # Spaces after marker for multi-line items

Related Rules

• MD013 - Line length (affects long list items)
• MD022 - Blank lines (around list blocks)
• MD031 - Code blocks in lists
• MD032 - Blank lines around lists

References

• CommonMark Spec - Lists
• GitHub Flavored Markdown - Task Lists
• mdBook - SUMMARY.md Format

MD004 - Unordered List Style

Unordered list style should be consistent.

Why This Rule Exists

Markdown supports three markers for unordered lists: -, *, and +. Using different markers inconsistently creates visual noise and can indicate accidental mixing of content from different sources.

Examples

Incorrect

- Item one
* Item two
+ Item three

Correct

- Item one
- Item two
- Item three

Or consistently using asterisks:

* Item one
* Item two
* Item three

Configuration

[MD004]
style = "dash"  # Options: "dash", "asterisk", "plus", "consistent"

When to Disable

• Documents intentionally using different markers to distinguish list types
• Importing content from multiple sources

Rule Details

• Rule ID: MD004
• Aliases: ul-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD005 - List item indentation
• MD006 - Lists start at beginning of line
• MD007 - Unordered list indentation
• MD029 - Ordered list prefix style

MD005 - List Item Indentation

List item indentation should be consistent within a list.

Why This Rule Exists

Inconsistent indentation within lists can cause rendering issues and makes documents harder to read in source form. Proper indentation also ensures nested lists render correctly.

Examples

Incorrect

- Item one
 - Item two (wrong indentation)
- Item three

Correct

- Item one
- Item two
- Item three

Nested Lists (Correct)

- Item one
  - Nested item
  - Another nested
- Item two

Configuration

This rule has no configuration options. It enforces consistent indentation within each list.

When to Disable

• Working with auto-generated content that has intentional spacing
• Documents with complex nested structures requiring manual control

Rule Details

• Rule ID: MD005
• Aliases: list-indent
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD004 - Unordered list style
• MD006 - Lists start at beginning of line
• MD007 - Unordered list indentation depth
• MD030 - Spaces after list markers

MD006 - List Start Left

Consider starting bulleted lists at the beginning of the line.

Why This Rule Exists

Lists that don't start at the beginning of the line can cause unexpected rendering behavior in some Markdown parsers. Starting lists at column 0 ensures consistent rendering across all platforms.

Examples

Incorrect

Some text:
  - Indented list item
  - Another indented item

Correct

Some text:

- List item at start of line
- Another item at start of line

Nested Lists (Allowed)

- Top level item
  - Nested item (indentation is fine for nesting)
  - Another nested item

Configuration

This rule has no configuration options.

When to Disable

• Documents with intentionally indented lists for specific formatting
• Content that uses indentation for semantic meaning

Rule Details

• Rule ID: MD006
• Aliases: ul-start-left
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD004 - Unordered list style
• MD005 - List item indentation consistency
• MD007 - Unordered list indentation
• MD023 - Headings start at beginning of line

MD007 - Unordered List Indentation

Unordered list indentation should use consistent spacing.

Why This Rule Exists

Proper indentation of nested lists ensures correct rendering and improves readability. Different Markdown parsers may interpret inconsistent indentation differently.

Examples

Incorrect (4-space indent when 2 expected)

- Item one
    - Nested too far
- Item two

Correct (2-space indent)

- Item one
  - Properly nested
  - Another nested item
- Item two

Correct (4-space indent with configuration)

- Item one
    - Nested with 4 spaces
    - Another nested item
- Item two

Configuration

[MD007]
indent = 2           # Spaces per indentation level (default: 2)
start_indented = false  # Allow first level to be indented

When to Disable

• Documents following a different indentation standard
• Content imported from tools using different conventions

Rule Details

• Rule ID: MD007
• Aliases: ul-indent
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD004 - Unordered list style
• MD005 - List item indentation consistency
• MD006 - Lists start at beginning of line
• MD029 - Ordered list prefix style

MD029 - Ordered List Prefix

Ordered list item prefix consistency.

Why This Rule Exists

Markdown supports different numbering styles for ordered lists. Consistent style improves readability and makes reordering items easier.

Styles

One-Based (All 1s)

1. First item
1. Second item
1. Third item

Advantage: Easy to reorder without renumbering.

Sequential (Ordered)

1. First item
2. Second item
3. Third item

Advantage: Source reflects rendered numbers.

Zero-Based

0. First item
0. Second item
0. Third item

Examples

Incorrect (Mixed)

1. First item
2. Second item
1. Third item

Correct

1. First item
2. Second item
3. Third item

Configuration

[MD029]
style = "one_or_ordered"  # Options: "one", "ordered", "zero", "one_or_ordered"

When to Disable

• Documents with intentional mixed numbering
• Content using numbers for reference purposes

Rule Details

• Rule ID: MD029
• Aliases: ol-prefix
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD004 - Unordered list style
• MD030 - Spaces after list markers

MD030 - Spaces After List Markers

Severity: Warning
Category: Lists
Auto-fix: ✓ Available

Rule Description

This rule ensures consistent spacing after list markers (*, -, +, or numbers for ordered lists). Proper spacing improves readability and ensures correct parsing.

Why This Rule Exists

Consistent list marker spacing is important because:

• Ensures lists are properly recognized by all parsers
• Maintains uniform formatting across documents
• Improves readability and visual structure
• Some parsers require specific spacing for proper rendering

Examples

❌ Incorrect (violates rule)

*No space after asterisk
-No space after dash
+No space after plus
1.No space after number

*   Too many spaces
-    Excessive spacing
1.    Too much space in ordered list

✅ Correct

* Single space after asterisk
- Single space after dash
+ Single space after plus
1. Single space after number

* Consistent spacing
  * Nested items also follow rules
    * Multi-level nesting works

Configuration

[MD030]
ul_single = 1    # Spaces after single-line unordered list marker (default: 1)
ul_multi = 1     # Spaces after multi-line unordered list marker (default: 1)
ol_single = 1    # Spaces after single-line ordered list marker (default: 1)
ol_multi = 1     # Spaces after multi-line ordered list marker (default: 1)

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Adjust spacing after list markers to match configuration
• Handle both ordered and unordered lists
• Preserve list content and nesting
• Maintain proper indentation for nested lists

Apply Fix

# Fix list marker spacing
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your markdown processor has different spacing requirements
• You're working with generated content with specific formatting
• Your style guide requires different spacing patterns

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD030"]

Disable Inline

<!-- mdbook-lint-disable MD030 -->
*No space after marker allowed here
<!-- mdbook-lint-enable MD030 -->

Related Rules

• MD004 - Unordered list style
• MD005 - Consistent list indentation
• MD006 - Consider starting lists at the beginning of the line
• MD007 - Unordered list indentation
• MD029 - Ordered list item prefix
• MD032 - Lists surrounded by blank lines

References

• Original markdownlint rule
• CommonMark Specification - Lists

MD032 - Blanks Around Lists

Lists should be surrounded by blank lines.

Why This Rule Exists

Blank lines around lists ensure proper parsing and improve readability. Without blank lines, some Markdown parsers may not correctly identify list boundaries.

Examples

Incorrect

Some introductory text.
- Item one
- Item two
Following paragraph.

Correct

Some introductory text.

- Item one
- Item two

Following paragraph.

Configuration

This rule has no configuration options.

When to Disable

• Documents with compact formatting requirements
• Content with tight list-to-text flow

Rule Details

• Rule ID: MD032
• Aliases: blanks-around-lists
• Category: Structure
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD022 - Blanks around headings
• MD031 - Blanks around fenced code blocks
• MD058 - Blanks around tables

Whitespace Rules

These rules ensure consistent whitespace usage throughout your markdown documents.

Rules in This Category

Auto-fix Available ✓

• MD009 - No trailing spaces
• MD010 - Hard tabs
• MD012 - Multiple consecutive blank lines
• MD027 - Multiple spaces after blockquote symbol
• MD047 - Files should end with a single newline

Why Whitespace Matters

Consistent whitespace usage:

• Improves readability and maintainability
• Prevents version control issues (unnecessary diffs)
• Ensures consistent rendering across different viewers
• Follows standard text file conventions
• Reduces file size

Quick Configuration

# .mdbook-lint.toml

# Configure MD009 - Trailing spaces
[MD009]
br_spaces = 2  # Allow 2 spaces for line breaks

# Configure MD010 - Hard tabs
[MD010]
spaces_per_tab = 4  # Convert tabs to 4 spaces

# Configure MD012 - Multiple blank lines
[MD012]
maximum = 1  # Allow max 1 consecutive blank line

# Configure MD027 - Blockquote spacing
[MD027]
spaces = 1  # Require 1 space after >

Disable All Whitespace Rules

# .mdbook-lint.toml
disabled_rules = ["MD009", "MD010", "MD012", "MD027", "MD047"]

Related Categories

• Heading Rules - Heading formatting and structure
• List Rules - List formatting and indentation

MD009 - No Trailing Spaces

This rule checks for trailing spaces at the end of lines.

Why This Rule Exists

Trailing spaces are usually unintentional and can cause issues:

• They're invisible in most editors, making them hard to spot
• They can cause unexpected behavior in version control systems
• They may render differently across different markdown processors
• They increase file size unnecessarily

Examples

❌ Incorrect (violates rule)

This line has trailing spaces   ← spaces
This one has a tab at the end	← tab
Multiple spaces here    ← spaces

(Where arrows indicate invisible whitespace characters)

✅ Correct

This line has no trailing spaces
This one is clean too
Two spaces for line break are allowed  
when configured (br_spaces = 2)

Configuration

[MD009]
br_spaces = 2  # Number of trailing spaces allowed for line breaks (default: 2)
strict = false # If true, disallow even configured line break spaces (default: false)

Automatic Fix

This rule supports automatic fixing. The fix will:

• Remove all trailing whitespace from lines
• Preserve configured line break spaces (typically 2 spaces)
• Maintain the line's content and structure

When to Disable

Consider disabling this rule if:

• Your project intentionally uses trailing spaces for formatting

Rule Details

• Rule ID: MD009
• Aliases: no-trailing-spaces
• Category: Whitespace
• Severity: Warning
• Automatic Fix: ✅ Available

Configuration Options

[MD009]
br_spaces = 2  # Number of spaces allowed for line breaks (default: 2)
strict = false # If true, disallow even configured line break spaces (default: false)

Understanding Line Breaks

Markdown supports two types of line breaks:

Hard Line Break (Two Spaces)

First line  
Second line on new line

Renders as:

First line
Second line on new line

Paragraph Break (Blank Line)

First paragraph

Second paragraph

Renders as:

First paragraph

Second paragraph

Common Issues and Solutions

Invisible Trailing Spaces

Problem: Spaces at line ends are invisible in most editors.

This line has spaces    ← invisible spaces
Another line with tab	← invisible tab

Solution: Configure your editor to show whitespace or use the automatic fix.

This line has no trailing spaces
Another clean line

Inconsistent Line Break Handling

Problem: Different markdown processors handle trailing spaces differently.

Some text   
More text    
Final text     

Solution: Use exactly two spaces for line breaks when needed.

Some text  
More text  
Final text

Editor Configuration

Visual Studio Code

Add to settings.json:

{
  "files.trimTrailingWhitespace": true,
  "markdown.preview.breaks": true,
  "[markdown]": {
    "files.trimTrailingWhitespace": false
  }
}

Vim

Add to .vimrc:

" Show trailing spaces
set list listchars=trail:·

" Remove trailing spaces on save
autocmd BufWritePre * %s/\s\+$//e

Sublime Text

Add to preferences:

{
  "trim_trailing_white_space_on_save": true,
  "draw_white_space": ["all"]
}

Version Control Considerations

Git Configuration

Configure Git to warn about trailing whitespace:

git config core.whitespace trailing-space

Pre-commit Hooks

Use a pre-commit hook to catch trailing spaces:

#!/bin/sh
# .git/hooks/pre-commit
exec git diff --check --cached

When Line Break Spaces Are Needed

Sometimes two trailing spaces are intentional:

Poetry and Verses

Roses are red  
Violets are blue  
Markdown is great  
And so are you  

Addresses

123 Main Street  
Suite 100  
Anytown, ST 12345  

Preserving Formatting

Name:     John Doe  
Email:    john@example.com  
Phone:    555-1234  

Performance Impact

Trailing spaces can impact:

1. File Size: Unnecessary whitespace increases file size
2. Diff Noise: Changes to trailing spaces clutter version control
3. Search/Replace: Invisible characters can break patterns
4. Copy/Paste: Trailing spaces may cause unexpected behavior

Automatic Fix Behavior

The automatic fix will:

1. Remove all trailing whitespace from each line
2. Preserve exactly br_spaces spaces when configured (default: 2)
3. Handle tabs and mixed whitespace
4. Maintain line endings (LF/CRLF)

Fix Examples

Before:

Text with spaces    
Text with tab    
Text with mixed       

After (default config):

Text with spaces
Text with tab
Text with mixed

After (br_spaces=2, preserving line breaks):

Paragraph text
Line break needed  
Next line

Related Rules

• MD010 - Hard tabs
• MD012 - Multiple consecutive blank lines
• MD047 - Files should end with a single newline

References

• CommonMark Spec - Hard Line Breaks
• GitHub Flavored Markdown - Line Breaks

MD010 - Hard Tabs

Severity: Warning
Category: Whitespace
Auto-fix: ✓ Available

Rule Description

This rule checks for hard tab characters in the document and suggests replacing them with spaces for consistency.

Why This Rule Exists

Hard tabs can cause formatting inconsistencies:

• Tab width varies between editors (2, 4, or 8 spaces)
• Mixing tabs and spaces leads to misaligned text
• Different markdown renderers may handle tabs differently
• Code blocks and indentation become unpredictable

Examples

❌ Incorrect (violates rule)

→   This line starts with a tab
-→  List item with tab after marker
```→   Code block with tab indent

(Where → represents a tab character)

✅ Correct

    This line uses spaces for indentation
- List item with spaces after marker

```    Code block with space indent

Configuration

[MD010]
code_blocks = true  # Check for tabs in code blocks (default: true)
spaces_per_tab = 4  # Number of spaces to replace each tab with (default: 4)

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Replace each tab character with the configured number of spaces
• Preserve the visual indentation of your content
• Handle tabs in all contexts (text, lists, code blocks)

Apply Fix

# Fix all tab issues in your markdown files
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your project requires hard tabs (e.g., Makefiles in code examples)
• You're working with legacy content that uses tabs consistently
• Your team has standardized on tabs instead of spaces

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD010"]

Disable Inline

<!-- mdbook-lint-disable MD010 -->
→   Content with tabs allowed here
<!-- mdbook-lint-enable MD010 -->

Related Rules

• MD009 - No trailing spaces
• MD012 - Multiple consecutive blank lines
• MD047 - Files should end with newline

References

• Original markdownlint rule
• Tabs vs Spaces debate

MD012 - Multiple Consecutive Blank Lines

Severity: Warning
Category: Whitespace
Auto-fix: ✓ Available

Rule Description

This rule checks for multiple consecutive blank lines in the document. Excessive blank lines add unnecessary whitespace without improving readability.

Why This Rule Exists

Multiple consecutive blank lines create issues:

• Inconsistent spacing throughout documents
• Unnecessary vertical space in rendered output
• Potential confusion about section boundaries
• Increased file size without benefit

Examples

❌ Incorrect (violates rule)

# Heading

First paragraph.

Second paragraph with too many blank lines above.

Third paragraph with even more blank lines.

✅ Correct

# Heading

First paragraph.

Second paragraph with single blank line.

Third paragraph properly spaced.

Configuration

[MD012]
maximum = 1  # Maximum consecutive blank lines allowed (default: 1)

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Reduce multiple consecutive blank lines to the configured maximum
• Preserve intentional spacing at the maximum level
• Handle blank lines anywhere in the document

Apply Fix

# Fix excessive blank lines
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your style guide requires multiple blank lines for visual separation
• You're working with generated content that uses specific spacing
• You need extra spacing for ASCII art or diagrams

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD012"]

Disable Inline

<!-- mdbook-lint-disable MD012 -->
Content with multiple

blank lines allowed here
<!-- mdbook-lint-enable MD012 -->

Related Rules

• MD009 - No trailing spaces
• MD010 - Hard tabs
• MD047 - Files should end with newline

References

• Original markdownlint rule

MD027 - Multiple Spaces After Blockquote Symbol

Severity: Warning
Category: Blockquotes
Auto-fix: ✓ Available

Rule Description

This rule ensures there's only a single space (or no space) after the blockquote marker (>). Multiple spaces create inconsistent formatting.

Why This Rule Exists

Consistent blockquote spacing is important because:

• Maintains uniform appearance across documents
• Reduces unnecessary whitespace
• Follows standard markdown conventions
• Improves readability and predictability

Examples

❌ Incorrect (violates rule)

> Multiple spaces after blockquote marker
>
>

> Even more spaces here
>
>

> Too much spacing

✅ Correct

> Single space after marker
> Consistent spacing throughout
> Clean and readable
>
>
>

>No space is also valid
>When configured appropriately

Configuration

[MD027]
spaces = 1  # Number of spaces after blockquote marker (default: 1, can be 0)

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Adjust spaces after blockquote markers to match configuration
• Preserve blockquote content and nesting
• Handle multi-level blockquotes correctly

Apply Fix

# Fix blockquote spacing
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• Your style guide has different blockquote spacing requirements
• You're preserving legacy content with specific formatting
• You need variable spacing for visual emphasis

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD027"]

Disable Inline

<!-- mdbook-lint-disable MD027 -->
> Blockquote with custom spacing

<!-- mdbook-lint-enable MD027 -->

Related Rules

• MD028 - Blank line inside blockquote
• MD032 - Lists surrounded by blank lines

References

• Original markdownlint rule
• CommonMark Specification - Block Quotes

MD028 - No Blanks in Blockquote

Blank line inside blockquote.

Why This Rule Exists

A blank line inside a blockquote ends the quote in most Markdown parsers. This can cause unexpected rendering where content intended to be quoted appears as regular text.

Examples

Incorrect

> First paragraph of quote.
>

> Second paragraph (this is a new blockquote).

Correct

> First paragraph of quote.
>
> Second paragraph (still in same blockquote).

Multiple Paragraphs

> This is a long quote that spans
> multiple paragraphs.
>
> The blank line has a `>` marker
> to continue the blockquote.

Configuration

This rule has no configuration options.

When to Disable

• Documents intentionally using separate blockquotes
• Content where visual separation is desired

Rule Details

• Rule ID: MD028
• Aliases: no-blanks-blockquote
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes (adds > to blank lines)

Related Rules

• MD027 - Multiple spaces after blockquote symbol

MD047 - Files Should End with a Single Newline Character

Severity: Warning
Category: Whitespace
Auto-fix: ✓ Available

Rule Description

This rule ensures files end with exactly one newline character. This is a POSIX standard and helps with version control systems.

Why This Rule Exists

Files ending with a newline are important because:

• POSIX standard requires text files to end with a newline
• Git and other VCS show "No newline at end of file" warnings
• Prevents issues when concatenating files
• Ensures consistent file formatting
• Some tools expect the trailing newline

Examples

❌ Incorrect (violates rule)

# Document

Last line without newline```

Or with multiple newlines:

```markdown
# Document

Last line with multiple newlines

✅ Correct

# Document

Last line with single newline

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Add a newline if the file doesn't end with one
• Remove extra newlines if there are multiple
• Ensure exactly one newline at the end of the file

Apply Fix

# Fix file endings
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

When to Disable

Consider disabling this rule if:

• You're working with files that intentionally lack final newlines
• Your toolchain doesn't support files with trailing newlines
• You're dealing with generated content that doesn't include newlines

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD047"]

Disable for a Specific File

Add an inline directive at the top of the file you want to exclude:

<!-- mdbook-lint-disable MD047 -->

Related Rules

• MD009 - No trailing spaces
• MD010 - Hard tabs
• MD012 - Multiple consecutive blank lines

References

• Original markdownlint rule
• POSIX definition of text file

Link Rules

These rules ensure proper link formatting and validation in markdown documents.

Rules in This Category

Auto-fix Available ✓

• MD034 - Bare URL used

Other Link Rules

• MD011 - Reversed link syntax
• MD039 - Spaces inside link text
• MD042 - No empty links
• MD051 - Link fragments are valid
• MD052 - Reference links and images should use a label
• MD053 - Link and image reference definitions should be needed
• MD054 - Link and image style
• MD059 - Link and image reference style

Why Link Rules Matter

Proper link formatting:

• Ensures links are clickable in all renderers
• Improves accessibility with descriptive text
• Maintains consistent link style
• Prevents broken references
• Enhances document navigation

Common Link Formats

Inline Links

[Link text](https://example.com)
[Relative link](./other-page.md)
[Anchor link](#section-heading)

Reference Links

[Link text][reference]
[Another link][1]

[reference]: https://example.com
[1]: ./other-page.md

Autolinks

<https://example.com>
<user@example.com>

Quick Configuration

# .mdbook-lint.toml

# No configuration for MD034 - it auto-fixes bare URLs

# Disable specific link rules
disabled_rules = ["MD051", "MD052"]

Best Practices

1. Use descriptive link text: Avoid "click here" or "link"
2. Prefer relative paths: For internal documentation links
3. Check anchors: Ensure heading anchors exist
4. Use reference style: For frequently used URLs
5. Wrap bare URLs: Use <URL> syntax or proper links

Related Categories

• mdBook Rules - mdBook-specific link validation
• Style Rules - General formatting rules

MD011 - Reversed Link Syntax

Reversed link syntax should be corrected.

Why This Rule Exists

A common typo when writing Markdown links is reversing the bracket order, writing ](url)[text instead of [text](url). This rule catches these mistakes before they break your rendered documentation.

Examples

Incorrect

Check out ](https://example.com)[this link for more info.

See ](./other-page.md)[the other page.

Correct

Check out [this link](https://example.com) for more info.

See [the other page](./other-page.md).

Configuration

This rule has no configuration options.

When to Disable

• Generally should not be disabled as reversed links never render correctly

Rule Details

• Rule ID: MD011
• Aliases: no-reversed-links
• Category: Content
• Severity: Error
• Auto-fix: Yes (swaps to correct order)

Related Rules

• MD034 - Bare URLs
• MD039 - Spaces inside link text
• MD042 - Empty links

MD034 - Bare URL Used

Severity: Warning
Category: Links
Auto-fix: ✓ Available

Rule Description

This rule flags bare URLs that should be enclosed in angle brackets or converted to proper markdown links. Bare URLs may not be clickable in all markdown renderers.

Why This Rule Exists

Proper URL formatting is important because:

• Ensures URLs are clickable in all markdown renderers
• Improves document accessibility
• Provides consistent link formatting
• Allows for descriptive link text

Examples

❌ Incorrect (violates rule)

Visit https://example.com for more information.

Check out http://github.com/user/repo

Documentation at www.example.org

✅ Correct

Visit <https://example.com> for more information.

Check out [this repository](http://github.com/user/repo)

Documentation at [example.org](https://www.example.org)

<!-- URLs in code blocks are ignored -->

git clone https://github.com/user/repo.git

Configuration

This rule has no configuration options.

Automatic Fix

This rule supports automatic fixing with --fix. The fix will:

• Wrap bare URLs in angle brackets (<URL>)
• Preserve surrounding text and formatting
• Skip URLs in code blocks and inline code
• Handle both HTTP and HTTPS URLs

Apply Fix

# Fix bare URLs
mdbook-lint lint --fix docs/

# Preview what would be fixed
mdbook-lint lint --fix --dry-run docs/

Manual Enhancement

After auto-fix, consider manually converting to descriptive links:

<!-- After auto-fix -->
Visit <https://example.com> for more information.

<!-- Better: manually add descriptive text -->
Visit [our website](https://example.com) for more information.

When to Disable

Consider disabling this rule if:

• Your markdown renderer automatically links bare URLs
• You're documenting URLs that shouldn't be clickable
• Your content includes many URLs in plain text format

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD034"]

Disable Inline

<!-- mdbook-lint-disable MD034 -->
Plain URL: https://example.com
<!-- mdbook-lint-enable MD034 -->

Related Rules

• MD011 - Reversed link syntax
• MD039 - Spaces inside link text
• MD042 - No empty links

References

• Original markdownlint rule
• CommonMark Specification - Autolinks

MD039 - Spaces Inside Link Text

Spaces inside link text brackets.

Why This Rule Exists

Leading or trailing spaces inside link text brackets create inconsistent formatting and may render with unwanted whitespace in the clickable text.

Examples

Incorrect

[ Click here ](https://example.com)

[  Documentation  ](./docs.md)

[ Link ](url)

Correct

[Click here](https://example.com)

[Documentation](./docs.md)

[Link](url)

Configuration

This rule has no configuration options.

When to Disable

• Generally should not be disabled as spaced link text is usually unintentional

Rule Details

• Rule ID: MD039
• Aliases: no-space-in-links
• Category: Links
• Severity: Warning
• Auto-fix: Yes (removes extra spaces)

Related Rules

• MD037 - Spaces inside emphasis
• MD038 - Spaces inside code spans
• MD042 - Empty links
• MD051 - Link fragments

MD042 - No Empty Links

No empty links allowed.

Why This Rule Exists

Empty links with no URL serve no purpose and indicate incomplete content or a mistake during editing. They create broken user experiences when clicked.

Examples

Incorrect

Click [here]() for more information.

See the [documentation]().

[Empty link]()

Correct

Click [here](https://example.com) for more information.

See the [documentation](./docs.md).

[Valid link](https://example.com)

Placeholder Links

If you need placeholders during drafting, use comments:

<!-- TODO: Add link -->
Click [here](#) for more information.

Configuration

This rule has no configuration options.

When to Disable

• Draft documents with intentional placeholders
• Templates where links are filled programmatically

Rule Details

• Rule ID: MD042
• Aliases: no-empty-links
• Category: Links
• Severity: Error
• Auto-fix: No

Related Rules

• MD011 - Reversed link syntax
• MD039 - Spaces inside link text
• MD051 - Link fragments
• MD052 - Reference links and images

MD051 - Link Fragments

Link fragments should be valid.

Why This Rule Exists

Fragment links (anchors) like #section-name should point to actual headings in the document. Invalid fragments create broken navigation.

Examples

Incorrect

# Introduction

See the [configuration](#config) section.

## Configuration Options

Content here.

The fragment #config doesn't match #configuration-options.

Correct

# Introduction

See the [configuration](#configuration-options) section.

## Configuration Options

Content here.

How Fragments Are Generated

Headings become fragments by:

1. Converting to lowercase
2. Replacing spaces with hyphens
3. Removing special characters

Configuration

This rule has no configuration options.

When to Disable

• Documents with custom anchor IDs
• Content using JavaScript-based navigation
• Files processed by tools that modify anchors

Rule Details

• Rule ID: MD051
• Aliases: link-fragments
• Category: Links
• Severity: Warning
• Auto-fix: No

Performance

This rule is optimized for large documents. It builds a heading index once and validates all fragments efficiently.

Related Rules

• MD024 - Duplicate headings
• MD042 - Empty links
• MD052 - Reference links and images
• MDBOOK002 - Internal link validation

MD052 - Reference Links and Images

Reference links and images should use a label that is defined.

Why This Rule Exists

Reference-style links like [text][label] must have a corresponding definition. Undefined references render as plain text instead of links.

Examples

Incorrect

Check out the [documentation][docs] for more info.

Visit [our website][site].

<!-- Missing definitions for 'docs' and 'site' -->

Correct

Check out the [documentation][docs] for more info.

Visit [our website][site].

[docs]: https://docs.example.com
[site]: https://example.com

Images

![Logo][logo]

[logo]: ./images/logo.png "Company Logo"

Configuration

[MD052]
# Labels that are never reported as undefined.
# Defaults cover task list checkboxes and GitHub-style admonitions.
ignored_labels = [" ", "x", "!note", "!tip", "!important", "!warning", "!caution"]

# Whether bare [label] shortcut references are validated. Default: false.
shortcut_syntax = false

shortcut_syntax

With the default false, only full [text][label] and collapsed [text][] references are checked. Bare [label] text is left alone, so prose such as - [web] Fix the sidebar is not reported as a broken link.

Set it to true to also validate shortcut references:

[MD052]
shortcut_syntax = true

Under true, [missing] is reported when no [missing]: definition exists.

When to Disable

• Documents where references are defined in included files
• Templates with programmatically injected definitions

Rule Details

• Rule ID: MD052
• Aliases: reference-links-images
• Category: Links
• Severity: Warning
• Auto-fix: No

Reference Link Syntax

<!-- Full reference -->
[Link text][label]

<!-- Collapsed reference (label matches text) -->
[Example][]

<!-- Shortcut reference -->
[Example]

<!-- Definition -->
[label]: url "Optional Title"

Related Rules

• MD042 - Empty links
• MD051 - Link fragments
• MD053 - Unused reference definitions

MD053 - Link and Image Reference Definitions

Link and image reference definitions should be needed.

Why This Rule Exists

Unused reference definitions clutter documents and may indicate dead links or incomplete edits. Keeping only used definitions improves maintainability.

Examples

Incorrect

Check out the [documentation](https://docs.example.com).

[unused]: https://example.com
[also-unused]: https://other.com

The definitions are never used.

Correct

Check out the [documentation][docs].

[docs]: https://docs.example.com

Or remove unused definitions:

Check out the [documentation](https://docs.example.com).

Configuration

[MD053]
ignored_definitions = []  # Definitions to ignore (e.g., for includes)

Ignoring Definitions

[MD053]
ignored_definitions = ["//", "TODO"]

When to Disable

• Documents with definitions used in included content
• Templates with conditional reference usage
• Files serving as definition libraries

Rule Details

• Rule ID: MD053
• Aliases: link-image-reference-definitions
• Category: Links
• Severity: Warning
• Auto-fix: No

Related Rules

• MD052 - Reference links must be defined
• MD054 - Link and image style

MD054 - Link and Image Style

Link and image style should be consistent.

Why This Rule Exists

Markdown supports inline and reference-style links. Consistent style throughout a document improves readability and maintainability.

Styles

Inline

[Link text](https://example.com)
![Alt text](image.png)

Reference (Full)

[Link text][ref]
![Alt text][img]

[ref]: https://example.com
[img]: image.png

Reference (Collapsed)

[Example][]

[Example]: https://example.com

Reference (Shortcut)

[Example]

[Example]: https://example.com

Examples

Incorrect (Mixed)

See [inline link](https://example.com) and [reference link][ref].

[ref]: https://other.com

Correct

See [inline link](https://example.com) and [other link](https://other.com).

Configuration

[MD054]
autolink = true           # Allow autolinks <https://example.com>
inline = true             # Allow inline style
full = true               # Allow full reference style
collapsed = true          # Allow collapsed reference style
shortcut = true           # Allow shortcut reference style
url_inline = true         # Allow inline for URLs only

When to Disable

• Documents with intentional style mixing
• Content where different styles serve different purposes

Rule Details

• Rule ID: MD054
• Aliases: link-image-style
• Category: Links
• Severity: Warning
• Auto-fix: No

Related Rules

• MD052 - Reference links must be defined
• MD053 - Unused reference definitions
• MD059 - Descriptive link text

MD059 - Descriptive Link Text

Link text should be descriptive.

Why This Rule Exists

Generic link text like "click here" or "this link" provides no context about the destination. Descriptive text improves accessibility and helps users understand where links lead.

Examples

Incorrect

For more information, [click here](https://docs.example.com).

See [this link](./guide.md) for details.

[Here](https://api.example.com) is the API documentation.

Read more [here](./faq.md).

Correct

For more information, see the [complete documentation](https://docs.example.com).

See the [installation guide](./guide.md) for details.

Read the [API documentation](https://api.example.com).

Read the [frequently asked questions](./faq.md).

Configuration

This rule has no configuration options.

When to Disable

• UI documentation where "click here" matches actual button text
• Content with intentionally brief link descriptions

Rule Details

• Rule ID: MD059
• Aliases: descriptive-link-text
• Category: Accessibility
• Severity: Warning
• Auto-fix: No

Common Non-Descriptive Phrases

The rule flags these common patterns:

• "click here"
• "here"
• "this link"
• "this"
• "link"
• "read more"

Why Descriptive Text Matters

1. Screen Readers: Users often navigate by links; "click here" provides no context
2. Scanning: Users scan pages looking for relevant links
3. SEO: Search engines use link text to understand content relationships
4. Mobile: Touch targets benefit from clear labels

Accessibility Standards

This rule helps comply with:

• WCAG 2.1 Success Criterion 2.4.4 (Link Purpose in Context)
• WCAG 2.1 Success Criterion 2.4.9 (Link Purpose Link Only)

Related Rules

• MD042 - No empty links
• MD045 - Images should have alt text

Code Rules

These rules ensure proper formatting of code blocks and inline code in markdown documents.

Rules in This Category

• MD040 - Fenced code blocks should have a language specified
• MD014 - Dollar signs used before commands without showing output
• MD031 - Fenced code blocks should be surrounded by blank lines
• MD038 - Spaces inside code span elements
• MD046 - Code block style
• MD048 - Code fence style

Why Code Rules Matter

Proper code formatting:

• Enables syntax highlighting for better readability
• Maintains consistency across code examples
• Improves copy-paste reliability
• Ensures proper rendering in different viewers
• Helps readers identify programming languages quickly

Code Block Styles

Fenced Code Blocks (Recommended)

```javascript
function example() {
    return "Hello, world!";
}
```

Indented Code Blocks

    function example() {
        return "Hello, world!";
    }

Inline Code

Use the `console.log()` function to debug.

Language Specifications

Common language tags for syntax highlighting:

Quick Configuration

# .mdbook-lint.toml

# Configure MD040 - Require language tags
[MD040]
allowed_languages = ["js", "python", "rust", "bash"]

# Configure MD046 - Code block style
[MD046]
style = "fenced"  # Options: "fenced", "indented", "consistent"

# Configure MD048 - Code fence style
[MD048]
style = "backtick"  # Options: "backtick", "tilde", "consistent"

Best Practices

1. Always specify language: Enables syntax highlighting
2. Use fenced blocks: More flexible than indented blocks
3. Surround with blank lines: Improves readability
4. Be consistent: Use the same style throughout
5. Escape special characters: Use backslash when needed

Shell Commands

# Good - shows command without prompt
npm install mdbook-lint

# Avoid - dollar sign without output
npm install mdbook-lint

Related Categories

• mdBook Rules - mdBook-specific code requirements
• Whitespace Rules - General spacing rules

MD014 - Dollar Signs in Commands

Dollar signs used before commands without showing output.

Why This Rule Exists

Including $ prompts in shell code blocks makes it harder for users to copy and paste commands. If the code block shows command output, the prompt helps distinguish input from output. Otherwise, it's just noise.

Examples

Incorrect

```bash
$ npm install
$ npm run build

### Correct (no prompts)

```markdown
```bash
npm install
npm run build

### Correct (showing output)

```markdown
```bash
$ echo "Hello"
Hello
$ ls
file1.txt  file2.txt

## Configuration

This rule has no configuration options.

## When to Disable

- Tutorial content where prompts help indicate user input
- Documents showing interactive shell sessions
- Content distinguishing between different shell types

## Rule Details

- **Rule ID**: MD014
- **Aliases**: no-dollar-signs, commands-show-output
- **Category**: Content
- **Severity**: Warning
- **Auto-fix**: Yes (removes `$` prefix)

## Related Rules

- [MD040](./md040.md) - Fenced code blocks should have language
- [MD046](./md046.md) - Code block style

MD031 - Blanks Around Fences

Fenced code blocks should be surrounded by blank lines.

Why This Rule Exists

Blank lines around code blocks improve readability and ensure consistent rendering. Some parsers may not correctly identify code blocks without surrounding blank lines.

Examples

Incorrect

Some text here.
```code
let x = 1;

More text here.

### Correct

```markdown
Some text here.

```code
let x = 1;

More text here.

## Configuration

```toml
[MD031]
list_items = true  # Apply rule inside list items (default: true)

When to Disable

• Documents with compact formatting requirements
• Content where code blocks intentionally flow with text

Rule Details

• Rule ID: MD031
• Aliases: blanks-around-fences
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD022 - Blanks around headings
• MD032 - Blanks around lists
• MD040 - Fenced code blocks language
• MD046 - Code block style

MD038 - Spaces Inside Code Spans

Spaces inside code span markers.

Why This Rule Exists

Extra spaces inside backticks create inconsistent code formatting. The spaces become part of the rendered code, which usually isn't intended.

Examples

Incorrect

Use the ` print() ` function.

Run ` npm install ` to install.

Correct

Use the `print()` function.

Run `npm install` to install.

Intentional Spaces

If you need a backtick inside code, use double backticks with spaces:

Use `` `backticks` `` for code.

Configuration

This rule has no configuration options.

When to Disable

• Documents using spaces for specific code formatting
• Content requiring literal spaces in code spans

Rule Details

• Rule ID: MD038
• Aliases: no-space-in-code
• Category: Code
• Severity: Warning
• Auto-fix: Yes (removes extra spaces)

Related Rules

• MD037 - Spaces inside emphasis
• MD039 - Spaces inside link text
• MD040 - Fenced code blocks language

MD040 - Fenced Code Blocks Should Have a Language Specified

Severity: Warning
Category: Code
Auto-fix: Not available

Rule Description

This rule ensures that fenced code blocks specify a language for syntax highlighting. Language tags improve readability and enable proper syntax highlighting in rendered output.

Why This Rule Exists

Language specifications are important because:

• Enables syntax highlighting in rendered markdown
• Improves code readability and comprehension
• Helps readers quickly identify the programming language
• Ensures consistent code block presentation
• Required by many documentation tools (including mdBook)

Examples

❌ Incorrect (violates rule)

```
function hello() {
    console.log("Hello, world!");
}
```

```
SELECT * FROM users WHERE active = true;
```

✅ Correct

```javascript
function hello() {
    console.log("Hello, world!");
}
```

```sql
SELECT * FROM users WHERE active = true;
```

```bash
echo "Shell commands also benefit from highlighting"
```

```text
Plain text can be explicitly marked
```

Configuration

[MD040]
allowed_languages = []  # List of allowed languages (empty = all allowed)
language_optional = false  # Whether language tag is optional (default: false)

Common Language Tags

When to Disable

Consider disabling this rule if:

• Your markdown renderer doesn't support syntax highlighting
• You have many code blocks where language is obvious from context
• You're using custom code block processors that don't require language tags

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD040"]

Disable Inline

<!-- mdbook-lint-disable MD040 -->
```
Code block without language tag
```
<!-- mdbook-lint-enable MD040 -->

Related Rules

• MD046 - Code block style
• MD048 - Code fence style
• MDBOOK001 - Code blocks should have language tags (mdBook-specific)

References

• Original markdownlint rule
• GitHub Flavored Markdown - Syntax Highlighting

MD046 - Code Block Style

Code block style should be consistent.

Why This Rule Exists

Markdown supports both fenced code blocks (triple backticks) and indented code blocks (4 spaces). Consistent style improves readability.

Styles

Fenced (Recommended)

```rust
fn main() {
    println!("Hello");
}
```

Indented

    fn main() {
        println!("Hello");
    }

Examples

Incorrect (Mixed)

```python
print("Hello")
```

    # Indented code block
    echo "World"

Correct (Consistent Fenced)

```python
print("Hello")
```

```bash
echo "World"
```

Configuration

[MD046]
style = "fenced"  # Options: "fenced", "indented", "consistent"

When to Disable

• Documents mixing styles intentionally
• Legacy content with established patterns

Rule Details

• Rule ID: MD046
• Aliases: code-block-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Why Fenced is Recommended

• Supports language specification for syntax highlighting
• Clearer visual boundaries
• Easier to copy and paste
• Works better with nested content

Related Rules

• MD031 - Blanks around fences
• MD040 - Fenced code blocks language
• MD048 - Code fence style

MD048 - Code Fence Style

Code fence style should be consistent.

Why This Rule Exists

Markdown supports two fence styles: backticks and tildes. Consistent style throughout a document improves readability and maintainability.

Styles

Backticks (Common)

```rust
let x = 1;
```

Tildes

~~~rust
let x = 1;
~~~

Examples

Incorrect (Mixed)

```python
print("Hello")
```

~~~bash
echo "World"
~~~

Correct

```python
print("Hello")
```

```bash
echo "World"
```

Configuration

[MD048]
style = "backtick"  # Options: "backtick", "tilde", "consistent"

When to Disable

• Documents with intentional style mixing
• Content with nested code blocks (tildes inside backticks)

Rule Details

• Rule ID: MD048
• Aliases: code-fence-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Nesting Code Blocks

To show code fences inside code blocks, use different styles:

````markdown
```rust
let x = 1;
```
````

Related Rules

• MD031 - Blanks around fences
• MD040 - Fenced code blocks language
• MD046 - Code block style

Style Rules

These rules enforce consistent styling choices throughout your markdown documents.

Rules in This Category

• MD013 - Line length
• MD003 - Heading style
• MD035 - Horizontal rule style
• MD036 - Emphasis used instead of a heading
• MD044 - Proper names should have correct capitalization
• MD049 - Emphasis style should be consistent
• MD050 - Strong style should be consistent

Why Style Rules Matter

Consistent style:

• Creates professional, polished documentation
• Improves readability and scanning
• Reduces cognitive load for readers
• Maintains brand and project consistency
• Facilitates team collaboration

Common Style Choices

Heading Styles

# ATX Style Heading (Recommended)

Setext Style Heading
====================

Emphasis Styles

*Italic with asterisks*
_Italic with underscores_

**Bold with asterisks**
__Bold with underscores__

Horizontal Rules

---
---

---

Quick Configuration

# .mdbook-lint.toml

# Configure MD013 - Line length
[MD013]
line_length = 100
code_blocks = false
tables = false

# Configure MD003 - Heading style
[MD003]
style = "atx"  # Options: "atx", "setext", "consistent"

# Configure MD035 - Horizontal rule style
[MD035]
style = "---"  # Use three hyphens

# Configure MD049 - Emphasis style
[MD049]
style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

# Configure MD050 - Strong style
[MD050]
style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

Style Guide Template

Create a consistent style guide for your project:

# .mdbook-lint.toml - Project Style Guide

# Line length for readability
[MD013]
line_length = 80

# ATX headings only
[MD003]
style = "atx"

# Consistent emphasis
[MD049]
style = "asterisk"

[MD050]
style = "asterisk"

# Three hyphens for horizontal rules
[MD035]
style = "---"

Best Practices

1. Choose and document: Pick a style and document it
2. Be consistent: Use the same style throughout
3. Consider your audience: Technical vs. general readers
4. Think about rendering: How it looks in your target output
5. Automate checks: Use CI/CD to enforce style

Related Categories

• Heading Rules - Detailed heading formatting
• Whitespace Rules - Spacing and indentation
• Code Rules - Code formatting standards

MD013 - Line Length

Severity: Warning
Category: Style
Auto-fix: Not available

Rule Description

This rule enforces a maximum line length for markdown files. Long lines can be difficult to read and review, especially in terminals and diff views.

Why This Rule Exists

Line length limits are important because:

• Improves readability in narrow windows and terminals
• Makes diffs easier to review in version control
• Follows traditional text formatting conventions
• Prevents horizontal scrolling in editors
• Facilitates side-by-side comparisons

Examples

❌ Incorrect (violates rule)

This is an extremely long line that goes on and on and on, exceeding the configured maximum line length and making it difficult to read in narrow terminals or when viewing diffs.

✅ Correct

This line is broken up into shorter segments.
It's easier to read and review.
Each line stays within the configured limit.

Configuration

[MD013]
line_length = 80        # Maximum line length (default: 80)
code_blocks = true      # Check code blocks (default: true)
tables = true           # Check tables (default: true)
headings = true         # Check headings (default: true)
ignore_reference_definitions = false  # Skip long reference definition lines (default: false)
strict = false          # Strict length (no leniency for URLs) (default: false)
stern = false           # Stern length (allow long lines with no spaces) (default: false)

Reference link definitions

A link or image reference definition puts the destination on its own line:

[some-long-label]: https://example.com/a/very/long/destination/that/exceeds/the/limit

The label and destination cannot be wrapped, so a long one triggers MD013 with no way to fix it. Set ignore_reference_definitions = true to skip these [label]: destination lines (used by both link and image references).

When to Disable

Consider disabling this rule if:

• Your team prefers no line length limits
• You're working with content that requires long lines (tables, URLs)
• Your documentation is primarily viewed in wide screens
• You have many long code examples

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MD013"]

Disable Inline

<!-- mdbook-lint-disable MD013 -->
This can be a very long line that exceeds the normal limits without triggering a violation.
<!-- mdbook-lint-enable MD013 -->

Disable for Specific Elements

[MD013]
# Keep line length check but exclude certain elements
code_blocks = false  # Don't check code blocks
tables = false       # Don't check tables

Tips for Compliance

1. Break at natural points: Sentences, clauses, or phrases
2. Use soft wrapping: Let your editor wrap visually while keeping semantic lines
3. Consider semantic line breaks: One sentence per line
4. Extract long URLs: Use reference-style links

<!-- Instead of -->
Check out [this very long link text](https://example.com/very/long/path/to/resource)

<!-- Use -->
Check out [this very long link text][1]

[1]: https://example.com/very/long/path/to/resource

Related Rules

• MD009 - No trailing spaces
• MD010 - Hard tabs

References

• Original markdownlint rule
• Semantic Line Breaks

MD035 - Horizontal Rule Style

Horizontal rule style should be consistent.

Why This Rule Exists

Markdown supports multiple horizontal rule syntaxes. Consistent style throughout a document improves readability and maintainability.

Styles

---

---


---


---


** *

All render as horizontal rules but mixing them is inconsistent.

Examples

Incorrect

Section one content.

---

Section two content.

---


Section three content.

Correct

Section one content.

---

Section two content.

---

Section three content.

Configuration

[MD035]
style = "---"  # Options: "---", "***", "___", "consistent"

When to Disable

• Documents with intentional style variation
• Content imported from multiple sources

Rule Details

• Rule ID: MD035
• Aliases: hr-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD003 - Heading style consistency
• MD004 - Unordered list style consistency

MD043 - Required Heading Structure

Required heading structure not found.

Why This Rule Exists

Some documents must follow a specific heading structure for consistency across a project. This rule enforces a predefined heading pattern.

Examples

Configuration

[MD043]
headings = ["# Title", "## Introduction", "## Usage", "## API", "## License"]

Incorrect

# My Project

## Getting Started

## API Reference

Missing required "Introduction" and has different heading names.

Correct

# Title

## Introduction

## Usage

## API

## License

Configuration 2

[MD043]
headings = []          # Required headings in order
match_case = true      # Case-sensitive matching (default: true)

Wildcards

Use * to allow any heading at a position:

[MD043]
headings = ["# *", "## Introduction", "##*"]

When to Disable

• Documents that don't follow a template
• Creative content without structure requirements
• Auto-generated files

Rule Details

• Rule ID: MD043
• Aliases: required-headings
• Category: Structure
• Severity: Warning
• Auto-fix: No

Use Cases

• README templates across repositories
• Documentation standards
• API documentation structure
• Legal documents with required sections

Related Rules

• MD001 - Heading increment
• MD024 - Duplicate headings
• MD025 - Single top-level heading

MD044 - Proper Names Capitalization

Proper names should have correct capitalization.

Why This Rule Exists

Brand names, product names, and technical terms often have specific capitalization. Consistent capitalization improves professionalism and readability.

Examples

Configuration

[MD044]
names = ["JavaScript", "GitHub", "macOS", "iOS"]
code_blocks = false  # Don't check inside code blocks

Incorrect

Install the package using Github.

This works on MacOS and IOS devices.

Learn javascript programming.

Correct

Install the package using GitHub.

This works on macOS and iOS devices.

Learn JavaScript programming.

Configuration 2

[MD044]
names = []            # List of proper names with correct capitalization
code_blocks = false   # Check inside code blocks (default: false)
html_elements = false # Check inside HTML elements (default: false)

Common Names

[MD044]
names = [
  "JavaScript", "TypeScript", "Node.js", "npm",
  "GitHub", "GitLab", "Bitbucket",
  "macOS", "iOS", "iPadOS", "watchOS", "tvOS",
  "MySQL", "PostgreSQL", "MongoDB", "SQLite",
  "Rust", "Python", "Ruby", "Kotlin"
]

When to Disable

• Documents where capitalization varies intentionally
• Code-heavy content where names appear in identifiers
• Historical documents preserving original text

Rule Details

• Rule ID: MD044
• Aliases: proper-names
• Category: Style
• Severity: Warning
• Auto-fix: No

Notes

The rule is smart about context:

• Ignores text inside code blocks (configurable)
• Ignores text inside inline code spans
• Ignores URLs and link destinations

Related Rules

• MD038 - Spaces inside code spans

Emphasis Rules

Rules for formatting bold and italic text.

Rules in This Category

Overview

Emphasis rules ensure consistent formatting of bold (**text**) and italic (*text*) text throughout your documents.

Common Issues

• Using **bold** on a line by itself as a pseudo-heading

• Spaces inside markers like **bold** that may not render

• Mixing asterisks and underscores inconsistently

Best Practices

• Use real headings (##) instead of bold text for sections
• Keep emphasis markers tight against text (no internal spaces)
• Choose one style (asterisks or underscores) and use it consistently

MD036 - Emphasis Instead of Heading

Emphasis used instead of a heading.

Why This Rule Exists

Using bold or italic text on its own line as a pseudo-heading breaks document structure. Real headings provide proper hierarchy for navigation, accessibility, and table of contents generation.

Examples

Incorrect

**Introduction**

This section introduces the topic.

*Getting Started*

Follow these steps to begin.

Correct

## Introduction

This section introduces the topic.

## Getting Started

Follow these steps to begin.

Configuration

[MD036]
punctuation = ".,;:!?。；：！？"  # Punctuation that indicates not a heading

Lines ending with punctuation are assumed to be emphasized text, not pseudo-headings.

When to Disable

• Documents using emphasis for visual styling
• Content where headings aren't appropriate
• Presentations or slides with different formatting needs

Rule Details

• Rule ID: MD036
• Aliases: no-emphasis-as-heading
• Category: Emphasis
• Severity: Warning
• Auto-fix: No

Why This Matters

Pseudo-headings created with emphasis:

• Don't appear in table of contents
• Break accessibility for screen readers
• Can't be linked to with anchors
• Don't contribute to document outline

Related Rules

• MD001 - Heading increment
• MD003 - Heading style
• MD022 - Blanks around headings

MD037 - Spaces Inside Emphasis

Spaces inside emphasis markers.

Why This Rule Exists

Spaces immediately inside emphasis markers may prevent proper rendering in some Markdown parsers. The emphasis won't be applied, leaving literal asterisks or underscores in the output.

Examples

Incorrect

This is **bold** text.


This is *italic* text.


Here is __also bold__ text.

Correct

This is **bold** text.

This is *italic* text.

Here is __also bold__ text.

Configuration

This rule has no configuration options.

When to Disable

• Generally should not be disabled as spaced emphasis rarely renders correctly

Rule Details

• Rule ID: MD037
• Aliases: no-space-in-emphasis
• Category: Emphasis
• Severity: Warning
• Auto-fix: Yes (removes spaces inside markers)

Related Rules

• MD038 - Spaces inside code spans
• MD039 - Spaces inside link text
• MD049 - Emphasis style
• MD050 - Strong style

MD049 - Emphasis Style

Emphasis style should be consistent.

Why This Rule Exists

Markdown supports two emphasis markers: asterisks and underscores. Consistent style improves readability and maintainability.

Styles

Asterisks

This is *italic* text.

Underscores

This is _italic_ text.

Examples

Incorrect (Mixed)

This is *italic* and this is _also italic_.

Use *consistent* formatting _throughout_ the document.

Correct

This is *italic* and this is *also italic*.

Use *consistent* formatting *throughout* the document.

Configuration

[MD049]
style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

When to Disable

• Documents with intentional style variation
• Content imported from multiple sources

Rule Details

• Rule ID: MD049
• Aliases: emphasis-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Note on Underscores

Underscores inside words are not treated as emphasis:

some_variable_name  <!-- Not italic, just text -->

Related Rules

• MD037 - Spaces inside emphasis
• MD050 - Strong style

MD050 - Strong Style

Strong emphasis style should be consistent.

Why This Rule Exists

Markdown supports two strong emphasis markers: double asterisks and double underscores. Consistent style improves readability.

Styles

Asterisks (Common)

This is **bold** text.

Underscores

This is __bold__ text.

Examples

Incorrect (Mixed)

This is **bold** and this is __also bold__.

Correct

This is **bold** and this is **also bold**.

Configuration

[MD050]
style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

| consistent | Match first occurrence |

When to Disable

• Documents with intentional style variation
• Content imported from multiple sources

Rule Details

• Rule ID: MD050
• Aliases: strong-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD037 - Spaces inside emphasis
• MD049 - Emphasis style

Table Rules

Rules for formatting Markdown tables.

Rules in This Category

Overview

Table rules ensure consistent and valid table formatting. Properly formatted tables render correctly across all Markdown parsers.

Common Issues

• Inconsistent pipe style (leading/trailing pipes)
• Rows with different numbers of columns
• Tables not separated from surrounding content

Best Practices

• Use leading and trailing pipes for clarity
• Ensure all rows have the same number of columns
• Surround tables with blank lines
• Align columns for readable source (optional)

Example Table

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

MD055 - Table Pipe Style

Table pipe style should be consistent.

Why This Rule Exists

Markdown tables can have leading and trailing pipes or omit them. Consistent style improves readability and source formatting.

Styles

Leading and Trailing (Recommended)

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

No Leading/Trailing

Header 1 | Header 2
---------|----------
Cell 1   | Cell 2

Leading Only

| Header 1 | Header 2
|----------|----------
| Cell 1   | Cell 2

Examples

Incorrect (Mixed)

| Header 1 | Header 2 |
|----------|----------|
Cell 1   | Cell 2

Correct

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Configuration

[MD055]
style = "leading_and_trailing"  # Options: see below

When to Disable

• Documents with tables from different sources
• Content where specific formatting is required

Rule Details

• Rule ID: MD055
• Aliases: table-pipe-style
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD056 - Table column count
• MD058 - Blanks around tables

MD056 - Table Column Count

Table column count should be consistent.

Why This Rule Exists

All rows in a table should have the same number of columns. Mismatched column counts cause rendering issues and indicate data entry errors.

Examples

Incorrect

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   |
| Cell 1   | Cell 2   | Cell 3   | Cell 4 |

Row 2 has too few columns, row 3 has too many.

Correct

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Empty Cells

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   |          | Cell 3   |
| Cell 4   | Cell 5   |          |

Configuration

This rule has no configuration options.

When to Disable

• Tables intentionally using colspan-like behavior
• Content from sources with non-standard table formats

Rule Details

• Rule ID: MD056
• Aliases: table-column-count
• Category: Structure
• Severity: Error
• Auto-fix: Yes (adds empty cells)

Related Rules

• MD055 - Table pipe style
• MD058 - Blanks around tables

MD058 - Blanks Around Tables

Tables should be surrounded by blank lines.

Why This Rule Exists

Blank lines around tables ensure proper parsing and improve readability. Some Markdown parsers require blank lines to correctly identify table boundaries.

Examples

Incorrect

Some text here.
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
More text here.

Correct

Some text here.

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

More text here.

Configuration

This rule has no configuration options.

When to Disable

• Documents with compact formatting requirements
• Content where tables flow tightly with surrounding text

Rule Details

• Rule ID: MD058
• Aliases: blanks-around-tables
• Category: Formatting
• Severity: Warning
• Auto-fix: Yes

Related Rules

• MD022 - Blanks around headings
• MD031 - Blanks around fenced code blocks
• MD032 - Blanks around lists
• MD055 - Table pipe style
• MD056 - Table column count

MD060 - Table Column Style

Table column style should be consistent.

Why This Rule Exists

Markdown table cells can be padded with spaces in different ways. Mixing styles within the same table, or between tables in the same document, makes source files harder to scan and signals that rows were edited by hand at different times without reformatting the table.

Styles

• Compact - no padding at all around cell content: |A|B|
• Tight - one or more spaces of padding around cell content: | A | B |
• Aligned - a table-level label rather than a cell-level one. A table is classified aligned when at least one of its cells has more than one trailing space, which is what happens when padding is used to line columns up. The cells of such a table are still individually classified as tight.

Because a cell is only ever classified compact or tight, the comparison the rule performs is padded against not padded. It never measures column widths, and it never counts padding beyond the first space.

By default the rule detects the style from the first table in the document and enforces it on every table, including that first one. A mismatch inside a single table is reported, which is what the example below shows.

Examples

Incorrect

| A | B |
|---|---|
|1| 2 |

The header row uses tight style (| A |), but the data row mixes compact (|1|) and tight (2) cells.

Correct

| A | B |
|---|---|
| 1 | 2 |

Every cell uses the same single-space padding.

Aligned Style

| Column 1 | Col 2 | Column 3 |
|----------|-------|----------|
| Value 1  | V2    | Value 3  |
| V4       | Val 5 | V6       |

Extra trailing spaces are never a violation. In consistent mode a table like this one is detected as aligned, and that detection then requires the rest of the document only to pad its cells: a plain | A | B | table passes against it.

Tables inside fenced code blocks are ignored.

Configuration

[MD060]
# Options: "aligned", "compact", "tight", "any", "consistent"
style = "consistent"

style

• consistent (default) - detect the style from the first table in the document and enforce it on every table, the first one included.
• tight - require at least one space of padding around cell content. It does not require exactly one: | A | passes, and so does a table whose padding varies per column. Only a cell with no padding at all is a violation.
• aligned - the same check as tight. It rejects cells with no padding and accepts every padded cell, so a plain | A | B | table passes. Nothing in the rule requires columns to line up when this is set; the only difference from tight is the word used in the violation message.
• compact - require no padding around cell content. Any padded cell is a violation.
• any - disable the check entirely; any mix of styles is allowed.

When to Disable

• Documents that assemble tables from multiple generated sources
• Content where table formatting is not worth normalizing

Rule Details

• Rule ID: MD060
• Aliases: table-column-style
• Category: Formatting
• Severity: Warning
• Auto-fix: No

Related Rules

• MD055 - Table pipe style
• MD056 - Table column count
• MD058 - Blanks around tables

Image Rules

Rules for image formatting and accessibility.

Rules in This Category

Overview

Image rules ensure that images are accessible and properly formatted.

Why Alt Text Matters

Alt text (alternative text) serves multiple purposes:

• Accessibility: Screen readers use alt text to describe images
• Fallback: Displays when images fail to load
• SEO: Search engines use alt text to understand image content

Best Practices

• Write descriptive alt text that conveys the image's purpose
• Keep alt text concise but informative
• For decorative images, use empty alt text ![](image.png)
• Describe charts and diagrams with their key data points

Example

![Bar chart showing 50% increase in sales from Q1 to Q4](sales-chart.png)

MD045 - Images Should Have Alt Text

Images should have alternate text (alt text).

Why This Rule Exists

Alt text is essential for accessibility. Screen readers use it to describe images to visually impaired users. It also displays when images fail to load.

Examples

Incorrect

![](image.png)

![][logo]

[logo]: logo.png

Correct

![Screenshot of the dashboard](image.png)

![Company logo][logo]

[logo]: logo.png "Company Logo"

Good Alt Text

![Bar chart showing sales growth from 2020 to 2024](sales-chart.png)

![Red error icon indicating a failed operation](error-icon.svg)

Configuration

This rule has no configuration options.

When to Disable

• Decorative images that don't convey information
• Documents where images are supplementary

Rule Details

• Rule ID: MD045
• Aliases: no-alt-text
• Category: Images
• Severity: Warning
• Auto-fix: Yes (adds placeholder alt text)

Writing Good Alt Text

Accessibility Standards

This rule helps comply with:

• WCAG 2.1 Success Criterion 1.1.1 (Non-text Content)
• Section 508 accessibility requirements

Related Rules

• MD033 - No inline HTML
• MD052 - Reference links and images

HTML Rules

Rules for inline HTML usage in Markdown.

Rules in This Category

Overview

HTML rules control the use of raw HTML within Markdown documents. While Markdown supports inline HTML, using it reduces portability and can introduce security concerns.

Why Avoid HTML

• Portability: Not all Markdown renderers support HTML
• Security: HTML can introduce XSS vulnerabilities
• Maintainability: Markdown is easier to read and maintain
• Consistency: Mixing HTML and Markdown creates inconsistent documents

When HTML Is Acceptable

Some features require HTML:

• Collapsible sections (<details>)
• Keyboard shortcuts (<kbd>)
• Subscript/superscript (<sub>, <sup>)
• Complex layouts not possible in Markdown

Configuration

Allow specific HTML elements while blocking others:

[MD033]
allowed_elements = ["details", "summary", "kbd", "br"]

MD033 - No Inline HTML

Inline HTML should be avoided.

Why This Rule Exists

Markdown documents should remain portable and renderable in environments that don't support HTML. Raw HTML also makes documents harder to maintain and can introduce security concerns in some contexts.

Examples

Incorrect

<div class="warning">
This is a warning message.
</div>

Click <a href="https://example.com">here</a> for more.

<br>

<img src="image.png" alt="An image">

Correct

> **Warning**: This is a warning message.

Click [here](https://example.com) for more.

![An image](image.png)

Configuration

[MD033]
allowed_elements = []  # HTML elements to allow (default: none)

Allow Specific Elements

[MD033]
allowed_elements = ["br", "details", "summary"]

When to Disable

• Documents requiring HTML features not in Markdown
• Content using HTML for accessibility features
• mdBook projects using HTML preprocessors

Rule Details

• Rule ID: MD033
• Aliases: no-inline-html
• Category: Content
• Severity: Warning
• Auto-fix: No

Common Allowed Elements

Related Rules

• MD045 - Images should have alt text

mdBook-Specific Rules

These rules are specifically designed for mdBook projects, validating mdBook-specific syntax, conventions, and structure.

Rules

Why mdBook-Specific Rules

mdBook extends standard Markdown with special features:

1. SUMMARY.md Structure: Defines book organization
2. Include Syntax: {{#include file.md}}
3. Playground Links: {{#playground file.rs}}
4. Hidden Lines: Lines starting with # in Rust code blocks
5. Quiz Support: Interactive quizzes in documentation
6. Custom Renderers: Different output formats

These rules ensure your mdBook project:

• Builds correctly
• Renders properly in all output formats
• Maintains consistent structure
• Follows mdBook best practices

SUMMARY.md Structure

The SUMMARY.md file is the backbone of any mdBook project:

# Summary

[Introduction](./introduction.md)

# User Guide

- [Installation](./guide/installation.md)
- [Getting Started](./guide/getting-started.md)
  - [Basic Usage](./guide/basic-usage.md)
  - [Advanced Usage](./guide/advanced-usage.md)

# Reference

- [Configuration](./reference/configuration.md)
- [API](./reference/api.md)

---

[Contributors](./contributors.md)

Rules MDBOOK002-MDBOOK007 validate various aspects of this structure.

Common mdBook Issues

Missing Language Tags

Problem: Code blocks without language tags don't get syntax highlighting.

fn main() { println!("No highlighting!"); }

Solution: Always specify the language.

```rust
fn main() {
    println!("Properly highlighted!");
}

### Broken Internal Links

**Problem**: Links to non-existent chapters break navigation.

```markdown
- [Missing Chapter](./does-not-exist.md)

Solution: Ensure all linked files exist.

Invalid SUMMARY.md Format

Problem: Incorrect indentation or syntax breaks book generation.

- [Chapter 1](./chapter1.md)
    - [Wrong indent](./sub.md)  # Should be 2 spaces, not 4
[Missing dash](./chapter2.md)    # Should be "- [...]"

Solution: Follow mdBook's SUMMARY.md conventions.

Integration with CI/CD

Use these rules in your CI pipeline:

# .github/workflows/mdbook.yml
name: mdBook Checks

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run mdbook-lint

        run: |

          cargo install mdbook-lint
          mdbook-lint check

Configuration

Enable only mdBook rules:

# .mdbook-lint.toml
[rules]
# Disable all standard rules
"MD*" = false

# Enable only mdBook rules
"MDBOOK*" = true

Or enable both sets:

[rules]
# Use defaults (all rules enabled)

# Customize specific mdBook rules
[MDBOOK001]
allow_missing = false

Best Practices

1. Run Checks Before Building: Catch issues early
2. Include in Pre-commit Hooks: Prevent broken commits
3. Document Exceptions: If disabling rules, explain why
4. Test Rendering: Lint checks complement, not replace, build tests
5. Version Control SUMMARY.md: Track structure changes

Related Standard Rules

Some standard rules are particularly relevant for mdBook:

• MD041 - First line should be a heading (important for chapters)
• MD025 - Single H1 (one main heading per chapter)
• MD051 - Link fragments (for cross-references)

References

• mdBook Documentation
• SUMMARY.md Format
• mdBook Specific Markdown

MDBOOK001 - Code Blocks Should Have Language Tags

Code blocks should have language tags.

This rule is triggered when code blocks don't have language tags for syntax highlighting. Proper language tags help with documentation clarity and proper rendering in mdBook.

Why This Rule Exists

mdBook uses language tags for:

• Syntax highlighting in rendered output
• Proper code formatting and display
• Enabling language-specific features (like line numbers, highlighting specific lines)
• Improving accessibility for screen readers
• Better SEO and content understanding

Examples

❌ Incorrect (violates rule)

```
fn main() {
    println!("Hello, world!");
}
```

✅ Correct

```rust
fn main() {
    println!("Hello, world!");
}
```

Other valid examples:

```bash
cargo build --release
```

```toml
[dependencies]
serde = "1.0"
```

```json
{
  "name": "example",
  "version": "1.0.0"
}
```

Special Language Tags

mdBook supports special language tags:

• text or plain - for plain text without highlighting
• console - for command-line output
• diff - for showing differences
• ignore - for Rust code that shouldn't be tested
• no_run - for Rust code that compiles but shouldn't run
• should_panic - for Rust code expected to panic

Configuration

This rule has no configuration options. All code blocks should have language tags.

When to Disable

Consider disabling this rule if:

• You have many legacy code blocks without language tags
• You're using a custom mdBook renderer that doesn't require language tags

Rule Details

• Rule ID: MDBOOK001
• Category: mdBook-specific
• Severity: Warning
• Automatic Fix: Not available (requires manual language identification)

Why Language Tags Matter in mdBook

Syntax Highlighting

mdBook uses language tags to apply syntax highlighting via highlight.js or similar libraries:

Without language tag:

```
fn main() {
    println!("Hello, world!");
}
```

Renders as plain text with no highlighting.

With language tag:

```rust
fn main() {
    println!("Hello, world!");
}
```

Renders with proper Rust syntax highlighting.

mdBook-Specific Features

Language tags enable mdBook-specific features:

Rust Playground Integration

fn main() {
    println!("This code can be run in the Rust Playground!");
}

Hidden Lines in Rust Code

```rust
# fn main() {
println!("Only this line is shown");
# }
```

Test Annotations

```rust,ignore
// This code won't be tested
fn example() {}
```

```rust,no_run
// This code is compiled but not run
fn main() {
    loop {} // Would hang if run
}
```

```rust,should_panic
// This code is expected to panic
fn main() {
    panic!("This is expected!");
}
```

Common Language Tags

Programming Languages

Special Tags

Examples by Use Case

Configuration Files

TOML (Cargo.toml):

```toml
[package]
name = "my-project"
version = "0.1.0"

[dependencies]
serde = "1.0"
```

JSON (package.json):

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.0.0"
  }
}
```

Command-Line Examples

Shell commands:

```bash
# Install mdbook-lint
cargo install mdbook-lint

# Run the linter
mdbook-lint check
```

Console output:

```console
$ cargo build
   Compiling my-project v0.1.0
    Finished dev [unoptimized] target(s) in 2.34s
```

Showing Changes

Diff format:

```diff
- Old line that was removed
+ New line that was added
  Unchanged line
```

Multi-language Examples

HTML with embedded CSS and JavaScript:

```html
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: sans-serif; }
    </style>
</head>
<body>
    <h1>Hello</h1>
    <script>
        console.log('Hello, world!');
    </script>
</body>
</html>
```

Choosing the Right Language Tag

Decision Tree

1. Is it code? → Use appropriate language tag
2. Is it terminal output? → Use console
3. Is it a diff? → Use diff
4. Is it plain text? → Use text or plain
5. Is it data? → Use format tag (json, yaml, toml)
6. Not sure? → Use text rather than no tag

Language Detection Tips

Look for characteristic syntax:

• Rust: fn, let, mut, impl, ::
• Python: def, import, : for blocks, no semicolons
• JavaScript: function, const, =>, var
• Shell: $, # for comments, command names
• JSON: {, }, :, quoted keys
• TOML: [sections], key = value, # comments

Edge Cases

Mixed Language Blocks

For templates or mixed content, choose the primary language:

```html
<!-- This is primarily HTML even though it contains CSS -->
<div style="color: red;">Content</div>
```

Unknown or Custom Languages

For unsupported languages, use text:

```text
CUSTOM_SYNTAX {
    nonstandard = syntax
}
```

File Names as Context

Sometimes include the filename for context:

```rust
// src/main.rs
fn main() {
    println!("Hello!");
}
```

Impact on mdBook Features

Search Indexing

Code blocks with language tags are better indexed for search.

Syntax Theme Support

Language tags enable proper theme application:

• Light themes show appropriate colors
• Dark themes adjust for readability
• Contrast themes maintain accessibility

Copy Button

mdBook's copy button works better with properly tagged code blocks.

Line Numbers

Some themes show line numbers only for tagged code blocks:

```rust,linenos
fn main() {
    println!("Line 1");
    println!("Line 2");
}
```

Configuration 2

This rule has no configuration options. All code blocks should have language tags for optimal mdBook rendering.

Related Rules

• MD040 - Fenced code blocks should have a language specified (standard rule)
• MD046 - Code block style
• MD048 - Code fence style

References

• mdBook - Code Blocks
• Highlight.js Languages
• CommonMark - Fenced Code Blocks

MDBOOK002 - Invalid Internal Link

Severity: Error
Category: mdBook-specific
Auto-fix: Not available

Rule Description

This rule validates internal links within mdBook projects, ensuring they point to valid files and anchors. Broken internal links create a poor reading experience and navigation issues.

Why This Rule Exists

Valid internal links are crucial because:

• Ensures readers can navigate between chapters
• Prevents 404 errors in generated documentation
• Maintains documentation integrity
• Enables proper mdBook navigation features
• Helps identify renamed or moved files

Examples

❌ Incorrect (violates rule)

<!-- Link to non-existent file -->
See [configuration](./configs.md) for details.

<!-- Link to non-existent anchor -->
Check the [installation section](./setup.md#install)

<!-- Broken relative path -->
Read more in [the guide](../guides/intro.md)

✅ Correct

<!-- Valid file link -->
See [configuration](./configuration.md) for details.

<!-- Valid anchor link -->
Check the [installation section](./getting-started.md#installation)

<!-- Correct relative path -->
Read more in [the introduction](./introduction.md)

<!-- External links are not checked -->
Visit [Rust website](https://www.rust-lang.org)

What This Rule Checks

1. File existence: Verifies linked .md files exist
2. Anchor validity: Confirms heading anchors are present
3. Path resolution: Validates relative paths from current file
4. SUMMARY.md links: Ensures all chapter links are valid

Configuration

[MDBOOK002]
check_anchors = false    # Validate same-document anchors (default: false)
allow_external = true    # Skip external URLs (default: true)
check_images = false     # Also validate image paths (default: false)

• check_anchors: when enabled, same-document anchor links ([text](#section)) are checked against the headings in the file. Anchors that point at another file (other.md#section) are validated by MDBOOK006, not here.
• allow_external: external URLs (http, https, mailto, ftp, tel) are skipped. Set it to false to report them instead, for books that must not link off-site.
• check_images: when enabled, image paths (![alt](path)) are resolved the same way link paths are.

Common Issues and Solutions

Issue: File Renamed

<!-- Before -->
[Old name](./old-filename.md)

<!-- After -->
[New name](./new-filename.md)

Issue: Heading Changed

<!-- Heading changed from "## Installation" to "## Setup" -->
<!-- Before -->
[Install](./guide.md#installation)

<!-- After -->
[Install](./guide.md#setup)

Issue: File Moved

<!-- File moved to subdirectory -->
<!-- Before -->
[Guide](./guide.md)

<!-- After -->
[Guide](./user-guide/guide.md)

When to Disable

Consider disabling this rule if:

• You're in the middle of a major restructuring
• Your build process generates files dynamically
• You have external link checking handled separately

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MDBOOK002"]

Disable Inline

<!-- mdbook-lint-disable MDBOOK002 -->
[Temporarily broken link](./todo.md)
<!-- mdbook-lint-enable MDBOOK002 -->

Tips for Compliance

1. Use relative paths: More maintainable than absolute paths
2. Update links when renaming: Use search and replace
3. Test navigation: Click through links after changes
4. Use anchor generation tools: Ensure correct anchor format

Anchor Format

mdBook generates anchors from headings using these rules:

• Convert to lowercase
• Replace spaces with hyphens
• Remove special characters
• Handle duplicates with numbers

## Hello World!     <!-- #hello-world -->
## User's Guide     <!-- #users-guide -->
## 1.2.3 Version    <!-- #123-version -->

Related Rules

• MD042 - No empty links
• MD051 - Link fragments are valid
• MDBOOK003 - SUMMARY.md structure
• MDBOOK006 - Cross-reference validation

References

• mdBook Documentation - SUMMARY.md
• mdBook Link Format

MDBOOK003 - Invalid SUMMARY.md Structure

Severity: Error
Category: mdBook-specific
Auto-fix: Not available

Rule Description

This rule validates that SUMMARY.md follows mdBook's required structure and conventions. The SUMMARY.md file defines your book's table of contents and must follow specific formatting rules.

Why This Rule Exists

Proper SUMMARY.md structure is essential because:

• mdBook uses it to generate navigation
• Incorrect structure causes build failures
• Defines the reading order of chapters
• Controls the book's hierarchical organization
• Enables proper sidebar navigation

Examples

❌ Incorrect (violates rule)

# Summary

[Introduction](./introduction.md)

- Part 1
  - [Chapter 1](./chapter1.md)
  
* [Chapter 2](./chapter2.md)  <!-- Mixed list markers -->

  - [Chapter 3](./chapter3.md)  <!-- Incorrect indentation -->
  
[](./empty.md)  <!-- Empty link text -->

- - [Double nested](./nested.md)  <!-- Invalid nesting -->

✅ Correct

# Summary

[Introduction](./introduction.md)

# User Guide

- [Getting Started](./getting-started.md)
  - [Installation](./installation.md)
  - [Configuration](./configuration.md)
- [Advanced Usage](./advanced.md)

# Reference

- [API Documentation](./api.md)
- [Configuration Reference](./config-ref.md)

---

[Contributors](./contributors.md)

SUMMARY.md Structure Rules

Required Elements

1. Title: Must start with # Summary
2. Prefix Chapter: Optional [Introduction](./intro.md) before numbered chapters
3. Numbered Chapters: Use consistent list markers (- or *)
4. Suffix Chapters: Optional unnumbered chapters after separator

Formatting Rules

• Consistent indentation: Use 2 or 4 spaces per level
• Consistent list markers: Use either - or * throughout
• Valid links: All links must have text and valid paths
• Proper nesting: Child chapters indented under parents
• Part headers: Use # Part Name for sections

Special Elements

# Summary

[Preface](./preface.md)          <!-- Prefix chapter -->

# Part I

- [Chapter 1](./ch1.md)           <!-- Numbered chapter -->
  - [Section 1.1](./ch1-1.md)     <!-- Nested chapter -->
- [Chapter 2](./ch2.md)
  - [Draft]()                     <!-- Draft chapter (no link) -->

---                               <!-- Separator -->

[Appendix A](./appendix-a.md)    <!-- Suffix chapter -->

Configuration

[MDBOOK003]
allow_draft_chapters = true    # Allow chapters without links (default: true)
require_part_headers = false   # Require part headers (default: false)
max_depth = 3                  # Maximum nesting depth (default: unlimited)

• allow_draft_chapters: draft entries are written [Title]() with an empty link. Set it to false to require every chapter to point at a file.
• require_part_headers: when enabled, a summary that lists chapters must also declare at least one part header (# Part title).
• max_depth: deepest chapter nesting allowed, counting top-level chapters as depth 1. Leave it unset for unlimited nesting.

Common Issues and Solutions

Issue: Mixed List Markers

<!-- Wrong -->
- [Chapter 1](./ch1.md)
* [Chapter 2](./ch2.md)

<!-- Correct -->
- [Chapter 1](./ch1.md)
- [Chapter 2](./ch2.md)

Issue: Incorrect Indentation

<!-- Wrong -->
- [Chapter 1](./ch1.md)
   - [Section](./sec.md)  <!-- 3 spaces -->

<!-- Correct -->
- [Chapter 1](./ch1.md)
  - [Section](./sec.md)   <!-- 2 spaces -->

Issue: Invalid Draft Syntax

<!-- Wrong -->
- [TODO](.)
- [Draft](/)

<!-- Correct -->
- [Draft]()

When to Disable

Consider disabling this rule if:

• You're using a custom mdBook theme with different requirements
• Your build process generates SUMMARY.md dynamically
• You're migrating from another documentation system

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MDBOOK003"]

Tips for Compliance

1. Use consistent indentation: Pick 2 or 4 spaces and stick with it
2. Order matters: Chapters appear in the order listed
3. Test the build: Run mdbook build to verify structure
4. Use draft chapters: For work-in-progress sections

Related Rules

• MDBOOK002 - Invalid internal link
• MDBOOK005 - Orphaned files
• MDBOOK025 - SUMMARY.md heading structure

References

• mdBook - SUMMARY.md Format
• mdBook Configuration

MDBOOK004 - No Duplicate Chapter Titles

Chapter titles should be unique across the book.

Why This Rule Exists

Duplicate chapter titles create confusion in navigation and can cause issues with mdBook's URL generation. Each chapter should have a distinct, identifiable title.

Examples

Incorrect (SUMMARY.md)

# Summary

- [Introduction](./intro.md)
- [Getting Started](./start.md)
- [Introduction](./advanced-intro.md)  <!-- Duplicate -->

Correct

# Summary

- [Introduction](./intro.md)
- [Getting Started](./start.md)
- [Advanced Introduction](./advanced-intro.md)

Configuration

[MDBOOK004]
case_sensitive = true                  # Case-sensitive comparison (default: true)
ignore_prefixes = ["Chapter", "Part"]  # Prefixes stripped before comparing (default: none)

• case_sensitive: with the default, "Setup" and "setup" are different titles. Set it to false to treat them as duplicates.
• ignore_prefixes: the first matching prefix is stripped from a title (along with the whitespace after it) before comparison, so "Chapter Setup" and "Setup" compare equal.

When to Disable

• Books with intentionally repeated section names
• Multi-part books where repetition is meaningful

Rule Details

• Rule ID: MDBOOK004
• Aliases: no-duplicate-chapter-titles
• Category: MdBook
• Severity: Warning
• Auto-fix: No

Impact

Duplicate titles can cause:

• Confusing navigation sidebar
• Ambiguous URL paths
• Search result confusion
• Poor user experience

Related Rules

• MD024 - No duplicate headings
• MDBOOK003 - SUMMARY.md structure
• MDBOOK025 - SUMMARY.md heading structure

MDBOOK005 - Orphaned Files

Severity: Warning
Category: mdBook-specific
Auto-fix: Not available

Rule Description

This rule detects markdown files in your mdBook source directory that are not referenced in SUMMARY.md. Orphaned files won't be included in the built book and represent unused or forgotten content.

Why This Rule Exists

Detecting orphaned files is important because:

• Identifies forgotten or lost content
• Helps maintain a clean project structure
• Prevents confusion about what's included in the book
• Finds files that should be deleted or added to SUMMARY.md
• Reduces repository size by identifying unused files

Examples

❌ Problematic Structure

src/
├── SUMMARY.md
├── introduction.md      ✓ (in SUMMARY.md)
├── chapter1.md         ✓ (in SUMMARY.md)
├── chapter2.md         ✓ (in SUMMARY.md)
├── old-chapter.md      ✗ (orphaned)
├── todo.md            ✗ (orphaned)
└── notes.md           ✗ (orphaned)

✅ Clean Structure

src/
├── SUMMARY.md
├── introduction.md      ✓ (in SUMMARY.md)
├── chapter1.md         ✓ (in SUMMARY.md)
├── chapter2.md         ✓ (in SUMMARY.md)
└── appendix.md         ✓ (in SUMMARY.md)

What This Rule Checks

The rule scans for:

1. All .md files in the source directory
2. Files referenced in SUMMARY.md
3. Reports files not in SUMMARY.md as orphaned

Special Cases

Files that are not considered orphaned:

• SUMMARY.md itself
• README.md (often used as index)
• Files in directories excluded by configuration
• Files matching ignore patterns

Configuration

[MDBOOK005]
ignore_patterns = ["drafts/**", "*.backup.md"]  # Patterns to ignore
check_nested = true                             # Check subdirectories (default: true)
exclude_readme = true                           # Don't report README.md (default: true)

Common Scenarios

Scenario 1: Renamed File

You renamed a chapter but forgot to update SUMMARY.md:

# Old file still exists but not in SUMMARY.md
src/old-name.md  → orphaned
src/new-name.md  → in SUMMARY.md

Solution: Delete the old file or update SUMMARY.md

Scenario 2: Work in Progress

You're drafting new content not ready for inclusion:

src/draft-chapter.md  → orphaned (intentionally)

Solution: Move to a drafts folder or add ignore pattern

Scenario 3: Included Files

You have files that are included by other files:

src/snippets/example.md  → orphaned (but included via {{#include}})

Solution: Add to ignore patterns or move to non-source directory

Handling Orphaned Files

Option 1: Add to SUMMARY.md

# Summary

- [Existing Chapter](./existing.md)
- [Previously Orphaned](./orphaned.md)  <!-- Add this line -->

Option 2: Delete the File

rm src/orphaned-file.md

Option 3: Move Outside Source Directory

mkdir archived
mv src/orphaned.md archived/

Option 4: Add to Ignore Patterns

[MDBOOK005]
ignore_patterns = ["drafts/**", "work-in-progress.md"]

When to Disable

Consider disabling this rule if:

• You intentionally keep reference files in the source directory
• Your build process dynamically generates SUMMARY.md
• You use many include files that aren't directly referenced
• You're in the middle of major restructuring

Disable in Config

# .mdbook-lint.toml
disabled_rules = ["MDBOOK005"]

Best Practices

1. Regular cleanup: Periodically review and remove orphaned files
2. Use drafts folder: Keep work-in-progress in a separate directory
3. Document intentional orphans: Add comments explaining why files are kept
4. Version control: Check git history before deleting orphaned files

Related Rules

• MDBOOK002 - Invalid internal link
• MDBOOK003 - SUMMARY.md structure
• MDBOOK006 - Cross-reference validation

References

• mdBook - SUMMARY.md
• mdBook Directory Structure

MDBOOK006 - Internal Cross-References

Internal cross-reference links must point to valid headings in target files.

Why This Rule Exists

Cross-references between chapters using anchor fragments must resolve to actual headings in the target file. Invalid fragments create broken navigation.

Examples

Incorrect

See the [configuration section](./config.md#settings) for details.

Where config.md has no ## Settings heading.

Correct

See the [configuration section](./config.md#configuration-options) for details.

Where config.md contains:

## Configuration Options

Content here.

How Fragments Are Generated

mdBook generates fragments from headings:

Configuration

This rule has no configuration options.

When to Disable

• Books using custom anchor IDs
• Content with JavaScript-based navigation

Rule Details

• Rule ID: MDBOOK006
• Aliases: internal-cross-references
• Category: MdBook
• Severity: Warning
• Auto-fix: No

Related Rules

• MD051 - Link fragments (same-file)
• MDBOOK002 - Internal link validation

MDBOOK007 - Include Validation

Include directives must point to existing files with valid syntax.

Why This Rule Exists

mdBook's {{#include}} directive embeds content from other files. Invalid paths or syntax cause build failures or missing content.

Examples

Incorrect

{{#include missing-file.rs}}

{{#include ../src/lib.rs:nonexistent_anchor}}

\{{include src/main.rs}}  <!-- Missing # -->

Correct

{{#include ../src/lib.rs}}

{{#include ../src/lib.rs:main_function}}

{{#include ./snippets/example.rs:5:10}}

Include Syntax

<!-- Full file -->
{{#include path/to/file.rs}}

<!-- Line range -->
{{#include path/to/file.rs:5:10}}

<!-- From line to end -->
{{#include path/to/file.rs:5:}}

<!-- Named anchor -->
{{#include path/to/file.rs:anchor_name}}

Configuration