.markdownlint.yaml

---
# MkDocs-compatible markdownlint configuration

# Default state for all rules
default: true

# Path to configuration file to extend
extends: null

# MD001/heading-increment : Heading levels should only increment by one level at a time
MD001: true

# MD003/heading-style : Heading style
MD003:
  # Use ATX style headings for MkDocs
  style: "atx"

# MD004/ul-style : Unordered list style
MD004:
  # MkDocs works best with dash style
  style: "dash"

# MD005/list-indent : Inconsistent indentation for list items at the same level
MD005: true

# MD007/ul-indent : Unordered list indentation
MD007:
  # Standard 4 space indent works better with MkDocs
  indent: 4
  start_indented: false
  start_indent: 4

# MD009/no-trailing-spaces : Trailing spaces
MD009:
  # Allow line breaks in MkDocs content
  br_spaces: 2
  list_item_empty_lines: true
  strict: false

# MD010/no-hard-tabs : Hard tabs
MD010:
  code_blocks: true
  # Allow tabs in some code languages
  ignore_code_languages: [
    "makefile", "Makefile", "python",
    "yaml", "yml", "sh", "bash", "markdown",
    "md", "toml", "ini", "toml",
    "json", "dockerfile", "toml",
    "plaintext", "text", "txt", "shell",
    "console", "mermaid", "plantuml",
    "puml", "ps1", "powershell"
  ]
  spaces_per_tab: 4

# MD011/no-reversed-links : Reversed link syntax
MD011: true

# MD012/no-multiple-blanks : Multiple consecutive blank lines
MD012: false,  # 🚫 Allow multiple consecutive blank lines

# MD013/line-length : Line length
MD013: false # 🚫 Disable line length restrictions (similar to mdformat --wrap=no)

# MD014/commands-show-output : Dollar signs used before commands without showing output
MD014: true

# MD018-MD023: Heading formatting rules
MD018: true
MD019: true
MD020: true
MD021: true
MD022: true
MD023: false  # Allow indented headings for MkDocs features

# MD024/no-duplicate-heading : Multiple headings with the same content
MD024:
  # Allow same headings in different sections (common in MkDocs)
  siblings_only: true

# MD025/single-title/single-h1 : Multiple top-level headings
MD025:
  # Configure for MkDocs frontmatter
  level: 1
  front_matter_title: "^\\s*(title|page.title)\\s*[:=]"

# MD026/no-trailing-punctuation : Trailing punctuation in heading
MD026:
  # Allow question marks in headings
  punctuation: ".,;:!。，；：！"

# MD027-MD030: Spacing and style rules
MD027: true
MD028: false  # Allow blank lines in blockquotes for MkDocs styling
MD029:
  style: "one_or_ordered"
MD030: true

# MD031/blanks-around-fences : Fenced code blocks should be surrounded by blank lines
MD031:
  list_items: true

# MD032/blanks-around-lists : Lists should be surrounded by blank lines
MD032: true

# MD033/no-inline-html : Inline HTML
MD033: false  # Disable inline HTML restriction completely for MkDocs templates

# MD034/no-bare-urls : Bare URL used
MD034: true

# MD035/hr-style : Horizontal rule style
MD035:
  style: "---"  # MkDocs standard

# MD036/no-emphasis-as-heading : Emphasis used instead of a heading
MD036:
  punctuation: ".,;:!?。，；：！？"

# MD037-MD039: Emphasis and links formatting
MD037: true
MD038: true
MD039: true

# MD040/fenced-code-language : Fenced code blocks should have a language specified
MD040: false # 🚫 Allow non-fenced code blocks (if needed)

# MD041/first-line-heading/first-line-h1 : First line in a file should be a top-level heading
MD041: false  # Disable requirement for first line to be heading for MkDocs templates

# MD042/no-empty-links : No empty links
MD042: false  # Allow placeholder links used in MkDocs templates

# MD043/required-headings : Required heading structure
MD043: false


# MD044/proper-names : Proper names should have the correct capitalization
MD044: false  # Disable proper names capitalization check for flexibility

# MD045/no-alt-text : Images should have alternate text (alt text)
MD045: true

# MD046/code-block-style : Code block style
MD046: false

# MD047/single-trailing-newline : Files should end with a single newline character
MD047: true

# MD048/code-fence-style : Code fence style
MD048:
  # Triple backticks are standard in MkDocs
  style: "backtick"

# MD049/emphasis-style : Emphasis style
MD049:
  style: "asterisk"  # Standard for MkDocs

# MD050/strong-style : Strong style
MD050:
  style: "asterisk"  # Standard for MkDocs

# MD051-MD058: Link and table formatting
MD051: false  # Disable link fragment checking for MkDocs compatibility
MD052: true
MD053:
  ignored_definitions: ["//", "#"]  # Allow MkDocs-specific reference formats
MD054:
  # Allow all link styles for maximum compatibility
  autolink: true
  inline: true
  full: true
  collapsed: true
  shortcut: true
  url_inline: true
MD055:
  style: "consistent"
MD056: true
MD058: true