Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Example Configuration

This page provides a complete, fully-commented example configuration file for mdbook-lint.

Quick Start

  1. Copy the configuration below to .mdbook-lint.toml in your project root
  2. Uncomment and modify only the settings you want to change
  3. All settings are optional - mdbook-lint works with sensible defaults

Complete Example Configuration

# mdbook-lint Example Configuration
# 
# This is a comprehensive example configuration file for mdbook-lint.
# Copy this file to `.mdbook-lint.toml` in your project root and customize as needed.
#
# All settings shown here are optional - mdbook-lint works with sensible defaults.
# Uncomment and modify only the settings you want to change.

# ============================================================================
# GLOBAL SETTINGS
# ============================================================================

# Exit with error code if warnings are found
# fail-on-warnings = false

# List of rules to disable globally
# disabled_rules = ["MD013", "MD033"]

# Default severity level for all rules (error, warning, info)
# default_severity = "warning"

# Paths to ignore when linting
# ignore_paths = ["target/", "vendor/", "*.backup.md"]

# ============================================================================
# STANDARD MARKDOWN RULES (MD001-MD059)
# ============================================================================

# ----------------------------------------------------------------------------
# Heading Rules
# ----------------------------------------------------------------------------

# MD001 - Heading levels should only increment by one level at a time
# [MD001]
# No configuration options

# MD002 - First heading should be a top-level heading (deprecated, use MD041)
# [MD002]
# level = 1  # Expected first heading level

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

# MD018 - No space after hash on atx style heading (auto-fix)
# [MD018]
# No configuration options

# MD019 - Multiple spaces after hash on atx style heading (auto-fix)
# [MD019]
# No configuration options

# MD020 - No space inside hashes on closed atx style heading (auto-fix)
# [MD020]
# No configuration options

# MD021 - Multiple spaces inside hashes on closed atx style heading (auto-fix)
# [MD021]
# No configuration options

# MD022 - Headings should be surrounded by blank lines
# [MD022]
# lines_above = 1  # Blank lines above heading
# lines_below = 1  # Blank lines below heading

# MD023 - Headings must start at the beginning of the line (auto-fix)
# [MD023]
# No configuration options

# MD024 - Multiple headings with the same content
# [MD024]
# siblings_only = false  # Only check sibling headings

# MD025 - Multiple top-level headings in the same document
# [MD025]
# level = 1  # Heading level to check
# front_matter_title = true  # Consider front matter title as heading

# MD026 - Trailing punctuation in heading
# [MD026]
# punctuation = ".,;:!。，；：！"  # Punctuation to check

# ----------------------------------------------------------------------------
# List Rules
# ----------------------------------------------------------------------------

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

# MD005 - Consistent list indentation
# [MD005]
# No configuration options

# MD006 - Consider starting lists at the beginning of the line
# [MD006]
# No configuration options

# MD007 - Unordered list indentation
# [MD007]
# indent = 2  # Spaces per indentation level
# start_indented = false  # Allow first level to be indented

# MD029 - Ordered list item prefix
# [MD029]
# style = "one_or_ordered"  # Options: "one", "ordered", "one_or_ordered"

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

# MD032 - Lists should be surrounded by blank lines
# [MD032]
# No configuration options

# ----------------------------------------------------------------------------
# Whitespace Rules
# ----------------------------------------------------------------------------

# MD009 - Trailing spaces (auto-fix)
# [MD009]
# br_spaces = 2  # Number of spaces for line break
# strict = false  # Strict mode (no line break spaces)
# list_item_empty_lines = false  # Allow empty list items

# MD010 - Hard tabs (auto-fix)
# [MD010]
# code_blocks = true  # Check code blocks
# spaces_per_tab = 4  # Spaces to replace each tab

# MD012 - Multiple consecutive blank lines (auto-fix)
# [MD012]
# maximum = 1  # Maximum consecutive blank lines

# MD027 - Multiple spaces after blockquote symbol (auto-fix)
# [MD027]
# spaces = 1  # Number of spaces after blockquote marker

# MD028 - Blank line inside blockquote
# [MD028]
# No configuration options

# MD047 - Files should end with a single newline character (auto-fix)
# [MD047]
# No configuration options

# ----------------------------------------------------------------------------
# Code Rules
# ----------------------------------------------------------------------------

# MD014 - Dollar signs used before commands without showing output
# [MD014]
# No configuration options

# MD031 - Fenced code blocks should be surrounded by blank lines
# [MD031]
# list_items = true  # Check code blocks in lists

# MD038 - Spaces inside code span elements
# [MD038]
# No configuration options

# MD040 - Fenced code blocks should have a language specified
# [MD040]
# allowed_languages = []  # List of allowed languages (empty = all)
# language_optional = false  # Language tag is optional

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

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

# ----------------------------------------------------------------------------
# Link and Image Rules
# ----------------------------------------------------------------------------

# MD011 - Reversed link syntax
# [MD011]
# No configuration options

# MD034 - Bare URL used (auto-fix)
# [MD034]
# No configuration options

# MD039 - Spaces inside link text
# [MD039]
# No configuration options

# MD042 - No empty links
# [MD042]
# No configuration options

# MD045 - Images should have alternate text (alt text)
# [MD045]
# No configuration options

# MD051 - Link fragments should be valid
# [MD051]
# No configuration options

# MD052 - Reference links and images should use a label that is defined
# [MD052]
# No configuration options

# MD053 - Link and image reference definitions should be needed
# [MD053]
# ignored_definitions = []  # Definitions to ignore

# MD054 - Link and image style
# [MD054]
# autolink = true  # Allow autolinks
# inline = true    # Allow inline links
# full = true      # Allow full reference links
# collapsed = true # Allow collapsed reference links
# shortcut = true  # Allow shortcut reference links
# url_inline = true  # Allow URLs as inline links

# MD059 - Link and image reference definitions should be sorted
# [MD059]
# No configuration options (coming soon)

# ----------------------------------------------------------------------------
# Style Rules
# ----------------------------------------------------------------------------

# MD013 - Line length
# [MD013]
# line_length = 80  # Maximum line length
# code_blocks = true  # Check code blocks
# tables = true  # Check tables
# headings = true  # Check headings
# strict = false  # Strict mode (no leniency)
# stern = false  # Stern mode (allow long lines without spaces)

# MD035 - Horizontal rule style
# [MD035]
# style = "---"  # Horizontal rule style

# MD036 - Emphasis used instead of a heading
# [MD036]
# punctuation = ".,;:!?。，；：！？"  # Punctuation at end

# MD037 - Spaces inside emphasis markers
# [MD037]
# No configuration options

# MD041 - First line in a file should be a top-level heading
# [MD041]
# level = 1  # Required heading level
# front_matter_title = true  # Consider front matter title

# MD043 - Required heading structure
# [MD043]
# headings = []  # Required heading structure
# match_case = false  # Case-sensitive matching

# MD044 - Proper names should have the correct capitalization
# [MD044]
# names = []  # List of proper names
# code_blocks = true  # Check code blocks
# html_elements = true  # Check HTML elements

# MD049 - Emphasis style should be consistent
# [MD049]
# style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

# MD050 - Strong style should be consistent
# [MD050]
# style = "asterisk"  # Options: "asterisk", "underscore", "consistent"

# ----------------------------------------------------------------------------
# Table Rules
# ----------------------------------------------------------------------------

# MD055 - Table pipe style
# [MD055]
# style = "leading_and_trailing"  # Options: "leading_only", "trailing_only", "leading_and_trailing", "no_leading_or_trailing"

# MD056 - Table column count
# [MD056]
# No configuration options

# MD058 - Tables should have rows
# [MD058]
# No configuration options

# ----------------------------------------------------------------------------
# HTML Rules
# ----------------------------------------------------------------------------

# MD033 - Inline HTML
# [MD033]
# allowed_elements = []  # HTML elements to allow

# ============================================================================
# MDBOOK-SPECIFIC RULES
# ============================================================================

# MDBOOK001 - Code blocks should have language tags for syntax highlighting
# [MDBOOK001]
# No configuration options

# MDBOOK002 - Internal link validation
# [MDBOOK002]
# check_anchors = true  # Validate heading anchors
# allow_external = true  # Skip external URLs
# check_images = false  # Also validate image paths

# MDBOOK003 - SUMMARY.md structure validation
# [MDBOOK003]
# allow_draft_chapters = true  # Allow chapters without links
# require_part_headers = false  # Require part headers
# max_depth = 3  # Maximum nesting depth

# MDBOOK004 - No duplicate chapter titles
# [MDBOOK004]
# case_sensitive = false  # Case-sensitive comparison
# ignore_prefixes = ["Chapter", "Part"]  # Prefixes to ignore

# MDBOOK005 - Orphaned files detection
# [MDBOOK005]
# ignore_patterns = ["drafts/**", "*.backup.md"]  # Patterns to ignore
# check_nested = true  # Check subdirectories
# exclude_readme = true  # Don't report README.md

# MDBOOK006 - Cross-reference validation
# [MDBOOK006]
# check_external = false  # Don't check external URLs
# ignore_missing = false  # Report missing files
# case_sensitive = false  # Case-sensitive anchor matching

# MDBOOK007 - Include directive syntax validation
# [MDBOOK007]
# check_line_ranges = true  # Validate line numbers exist
# allow_external = false  # Allow includes outside src/
# max_depth = 3  # Maximum directory traversal depth

# MDBOOK008 - Rustdoc include validation
# [MDBOOK008]
# check_compilation = false  # Try to compile included code
# allow_external = false  # Allow includes outside project
# validate_anchors = true  # Check anchor existence

# MDBOOK009 - Playground directive syntax
# [MDBOOK009]
# require_editable = false  # Require editable attribute
# validate_compilation = false  # Check if code compiles

# MDBOOK010 - Preprocessor configuration validation
# [MDBOOK010]
# check_math = true  # Validate math syntax
# check_mermaid = true  # Validate mermaid syntax
# allowed_preprocessors = ["katex", "mermaid", "admonish"]

# MDBOOK011 - Template syntax validation
# [MDBOOK011]
# template_dir = "./templates"  # Default template directory
# check_variables = true  # Validate variable substitution
# allow_missing_vars = false  # Allow undefined variables

# MDBOOK012 - Include line range validation
# [MDBOOK012]
# validate_bounds = true  # Check if line numbers exist
# warn_large_ranges = true  # Warn for ranges > 100 lines
# max_range_size = 100  # Maximum lines in a range
# prefer_anchors = true  # Suggest anchors over line numbers

# MDBOOK025 - Multiple H1 headings allowed in SUMMARY.md
# [MDBOOK025]
# No configuration options

# ============================================================================
# FILE-SPECIFIC OVERRIDES
# ============================================================================

# Override rules for specific files or patterns
# [[overrides]]
# path = "README.md"
# disabled_rules = ["MD041"]  # README doesn't need H1 as first line

# [[overrides]]
# path = "CHANGELOG.md"
# disabled_rules = ["MD024", "MD025"]  # Allow duplicate headings in changelog

# [[overrides]]
# path = "examples/**/*.md"
# disabled_rules = ["MD013"]  # No line length limit in examples
# [overrides.rules.MD009]
# br_spaces = 0  # No trailing spaces allowed in examples

# [[overrides]]
# path = "docs/api/**"
# [overrides.rules.MD013]
# line_length = 120  # Longer lines for API docs

# ============================================================================
# PREPROCESSOR CONFIGURATION
# ============================================================================

# Configuration for mdBook preprocessor mode
# [preprocessor]
# fail_on_warnings = true  # Fail the build on warnings
# renderer = ["html", "pdf"]  # Run for specific renderers

# ============================================================================
# OUTPUT CONFIGURATION
# ============================================================================

# [output]
# format = "github"  # Options: "github", "json", "checkstyle"
# file = "lint-report.json"  # Output to file instead of stdout
# verbose = false  # Verbose output
# quiet = false  # Suppress non-error output
# color = "auto"  # Options: "auto", "always", "never"

Common Configuration Patterns

Minimal Configuration

For most projects, a minimal configuration is sufficient:

# .mdbook-lint.toml
fail-on-warnings = true
disabled_rules = ["MD013"]  # Disable line length if not needed

Strict Configuration

For projects requiring strict markdown compliance:

# Fail on any issues
fail-on-warnings = true

# Strict whitespace rules
[MD009]
strict = true  # No trailing spaces at all

[MD010]
code_blocks = true  # Check tabs in code blocks

# Require code block languages
[MD040]
language_optional = false

# Strict line length
[MD013]
line_length = 80
strict = true

Documentation Project

For technical documentation or mdBook projects:

# mdBook-specific checks
[MDBOOK002]
check_anchors = true
check_images = true

[MDBOOK005]
ignore_patterns = ["drafts/**", "archive/**"]

# Allow longer lines for documentation
[MD013]
line_length = 100
code_blocks = false  # Don't check code block line length
tables = false  # Don't check table line length

# Require proper code highlighting
[MD040]
language_optional = false

Blog or Content Site

For blogs or content-heavy sites:

# Relaxed rules for content
disabled_rules = [
    "MD013",  # No line length limit
    "MD033",  # Allow inline HTML
    "MD041"   # First line doesn't need to be H1
]

# Allow emphasis for styling
[MD036]
punctuation = ""  # Don't check for punctuation

# Consistent emphasis style
[MD049]
style = "asterisk"

[MD050]
style = "asterisk"

File-Specific Overrides

Example: Different Rules for Different Directories

# Strict rules for source documentation
[[overrides]]
path = "src/**/*.md"
[overrides.rules.MD013]
line_length = 80

# Relaxed rules for examples
[[overrides]]
path = "examples/**/*.md"
disabled_rules = ["MD013", "MD009"]

# Special rules for CHANGELOG
[[overrides]]
path = "CHANGELOG.md"
disabled_rules = [
    "MD024",  # Allow duplicate version headings
    "MD025"   # Allow multiple H1s for versions
]

Integration Configurations

GitHub Actions

# For CI/CD pipelines
fail-on-warnings = true

[output]
format = "github"  # GitHub Actions annotations

mdBook Preprocessor

[preprocessor]
fail_on_warnings = false  # Warning but don't fail build
renderer = ["html"]  # Only run for HTML output

Editor Integration

# For real-time feedback
[output]
format = "json"  # Machine-readable output
verbose = false  # Minimal output

Rule Categories Quick Reference

Disable All Rules in a Category

# Disable all heading rules
disabled_rules = [
    "MD001", "MD002", "MD003", "MD018", "MD019",
    "MD020", "MD021", "MD022", "MD023", "MD024",
    "MD025", "MD026"
]

# Disable all whitespace rules
disabled_rules = [
    "MD009", "MD010", "MD012", "MD027", "MD028", "MD047"
]

# Disable all list rules
disabled_rules = [
    "MD004", "MD005", "MD006", "MD007", "MD029",
    "MD030", "MD032"
]

Tips

  1. Start minimal: Begin with defaults and add configuration as needed
  2. Use overrides: Apply different rules to different parts of your project
  3. Document choices: Comment why certain rules are disabled
  4. Version control: Commit .mdbook-lint.toml to your repository
  5. Team agreement: Discuss and agree on rules with your team

Next Steps