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

Configuration Reference

Complete reference for all configuration options in mdbook-lint.

Global Configuration Options

preset

  • Type: string
  • Default: not set (use the complete stable default ruleset)
  • Valid values: "baseline"
  • Description: Select a curated, explicit base rule set. The baseline is a low-noise starting point for incremental CI adoption.
preset = "baseline"

Run mdbook-lint rules --preset baseline to inspect its exact, versioned membership: MD001, MD003, MD009, MD010, MD011, and MD014. The list is intentionally curated rather than derived from rule categories, so newly stable rules are not added implicitly. Removing the setting returns to the complete stable default set.

fail-on-warnings

  • Type: boolean
  • Default: false
  • Description: Exit with error code when warnings are found

fail-on-errors

  • Type: boolean
  • Default: true
  • Description: Exit with error code when errors are found

disabled-rules

  • Type: array<string>
  • Default: []
  • Description: List of rule IDs to disable globally
  • Example: ["MD013", "MD033"]

enabled-rules

  • Type: array<string>
  • Default: []
  • Description: List of rule IDs to explicitly enable. When non-empty this means "run only these rules", so every rule not listed is switched off.
  • Example: ["MD001", "MD002"]

experimental-rules

  • Type: array<string>
  • Default: []
  • Description: Experimental rules to run in addition to the stable defaults. Accepts rule IDs, or "*" for every experimental rule.
  • Example: ["MDBOOK010"] or ["*"]

Experimental rules do not run by default because their diagnostics may still change. Use this option rather than enabled-rules when you want an experimental rule alongside the normal rule set, since enabled-rules would disable everything else:

# Run all stable rules, plus MDBOOK010.
experimental-rules = ["MDBOOK010"]

--enable MDBOOK010 also activates an experimental rule, but follows the "only these rules" meaning of an explicit selection.

Run mdbook-lint rules to see which rules are experimental, or mdbook-lint rules --detailed for a table with a Default column showing whether each rule runs without configuration.

Rule-Selection Precedence

Rule selection uses the following precedence, from highest to lowest:

  1. CLI --enable selects exactly those rules and preserves its existing behavior of clearing configured disabled-rules.
  2. CLI --preset overrides a configured preset or enabled-rules base.
  3. A non-empty configured enabled-rules list selects exactly those rules and takes precedence over preset in the same file.
  4. Configured preset selects its explicit membership.
  5. With none of the above, all stable default rules run.

Configured disabled-rules and CLI --disable subtract from a preset. CLI --preset conflicts with CLI --enable, --standard-only, and --mdbook-only. Categories, experimental-rules, and markdownlint-compatible do not modify an exact preset; mdbook-lint check warns when these ineffective combinations are configured.

enabled-categories

  • Type: array<string>
  • Default: []
  • Description: List of rule categories to enable
  • Valid values: headings, lists, whitespace, code, style, links, mdbook

disabled-categories

  • Type: array<string>
  • Default: []
  • Description: List of rule categories to disable

markdownlint-compatible

  • Type: boolean
  • Default: false
  • Description: Enable markdownlint compatibility mode (disables rules that are disabled by default in markdownlint)

deprecated-warning

  • Type: string
  • Default: "warn"
  • Description: How to handle deprecated rule warnings
  • Valid values: "warn", "info", "silent"

malformed-markdown

  • Type: string
  • Default: "warn"
  • Description: How to handle malformed markdown
  • Valid values: "error", "warn", "skip"

Rules Section Configuration

rules.default

  • Type: boolean
  • Default: true
  • Description: Whether rules are enabled by default

rules.enabled

  • Type: table<string, boolean>
  • Description: Map of rule IDs to enable when default = false

rules.disabled

  • Type: table<string, boolean>
  • Description: Map of rule IDs to disable when default = true

Example:

[rules]
default = false

[rules.enabled]
MD001 = true
MD002 = true
MD009 = true

Rule-Specific Configuration

MD002 - First heading should be a top-level heading

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

MD003 - Heading style

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

MD004 - Unordered list style

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

MD007 - Unordered list indentation

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

MD009 - Trailing spaces

[MD009]
br_spaces = 2  # Spaces for line breaks (default: 2)
list_item_empty_lines = false  # Allow spaces in empty list items
strict = false  # Strict mode for all trailing spaces

MD010 - Hard tabs

[MD010]
code_blocks = true  # Include code blocks (default: true)
spaces_per_tab = 4  # Spaces per tab for reporting (default: 4)

MD012 - Multiple consecutive blank lines

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

MD013 - Line length

[MD013]
line_length = 80  # Maximum line length (default: 80)
code_blocks = false  # Check code blocks
tables = false  # Check tables
headings = true  # Check headings
heading_line_length = 80  # Separate limit for headings
strict = false  # Strict length checking
stern = false  # Stern length checking

MD024 - Multiple headings with same content

[MD024]
siblings_only = false  # Only check sibling headings (default: false)

MD025 - Multiple top-level headings

[MD025]
level = 1  # Heading level to check (default: 1)
front_matter_title = true  # Use front matter title

MD026 - Trailing punctuation in heading

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

MD029 - Ordered list item prefix

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

MD030 - Spaces after list markers

[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

MD035 - Horizontal rule style

[MD035]
style = "consistent"  # Style to enforce or "consistent"

MD036 - Emphasis used instead of heading

[MD036]
punctuation = ".,;:!?"  # Punctuation at end (default: ".,;:!?")

MD043 - Required heading structure

[MD043]
headings = ["# Summary", "## Overview"]  # Required headings in order
required_headings = ["# Summary", "## Overview"]  # Alternative name
headers = ["# Summary", "## Overview"]  # Alternative name (deprecated)

MD044 - Proper names should have correct capitalization

[MD044]
names = ["JavaScript", "GitHub", "TypeScript"]  # Proper names
code_blocks = false  # Include code blocks
html_elements = false  # Include HTML elements

MD046 - Code block style

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

MD048 - Code fence style

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

MD049 - Emphasis style

[MD049]
style = "consistent"  # Options: "consistent", "asterisk", "underscore"

MD050 - Strong style

[MD050]
style = "consistent"  # Options: "consistent", "asterisk", "underscore"

MD051 - Link fragments should be valid

[MD051]
# No configuration options

MD052 - Reference links and images should use label

[MD052]
shortcut_syntax = false  # Allow shortcut syntax

MD053 - Link and image reference definitions need labels

[MD053]
ignored_definitions = ["//"]  # Definitions to ignore

MD054 - Link and image reference definitions should be used

[MD054]
# No configuration options

MD055 - Table pipe style

[MD055]
style = "consistent"  # Options: "consistent", "leading_only", "trailing_only", "leading_and_trailing", "no_leading_or_trailing"

MD056 - Table column count

[MD056]
# No configuration options

MD058 - Tables should be surrounded by blank lines

[MD058]
# No configuration options

MD059 - Tables should not have empty cells

[MD059]
allowed_corner_cells = false  # Allow empty corner cells

mdBook-Specific Rules

mdBook-specific rules (MDBOOK001-MDBOOK025) generally don't have configuration options, as they check for mdBook-specific patterns and conventions.

Configuration File Examples

Minimal Configuration

disabled-rules = ["MD013", "MD033"]

Comprehensive Configuration

fail-on-warnings = true
fail-on-errors = true
markdownlint-compatible = false
deprecated-warning = "warn"
malformed-markdown = "error"

enabled-categories = ["headings", "lists"]
disabled-rules = ["MD041"]

[MD002]
level = 1

[MD003]
style = "atx"

[MD007]
indent = 2
start_indented = false

[MD009]
br_spaces = 2
strict = false

[MD013]
line_length = 100
code_blocks = false
tables = false

[MD024]
siblings_only = true

[MD029]
style = "ordered"

[MD030]
ul_single = 1
ol_single = 1

[MD044]
names = ["JavaScript", "TypeScript", "GitHub", "mdBook"]
code_blocks = false

Using Rules Section

[rules]
default = false

[rules.enabled]
MD001 = true
MD002 = true
MD003 = true
MD009 = true
MD047 = true

[MD003]
style = "atx"

[MD009]
br_spaces = 2