mdformat-mkdocs

An mdformat plugin for mkdocs and packages commonly used with MkDocs (mkdocs-material, mkdocstrings, and python-markdown)

In addition, mdformat-mkdocs will intentionally provide support for Zensical, which is working towards feature parity with mkdocs (as of mid-2026) and may add features ahead of mkdocs.

Supports:

• Indents are converted to four-spaces instead of two
  • Note: when specifying --align-semantic-breaks-in-lists, the nested indent for ordered lists is three, but is otherwise a multiple of four
• Unordered list bullets are converted to dashes (-) instead of *
• By default, ordered lists are standardized on a single digit (1. or 0.) unless --number is specified, then mdformat-mkdocs will apply consecutive numbering to ordered lists for consistency with mdformat
• MkDocs-Material Admonitions*
  • *Note: mdformat-admon will format the same admonitions, but for consistency with the mkdocs styleguide, an extra space will be added by this package (#22)
• MkDocs-Material Content Tabs*
  • *Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
• MkDocs-Material Definition Lists
• mkdocstrings Injection Blocks
  • Preserves ::: identifier blocks and their indented YAML options verbatim, including when nested inside lists with --align-semantic-breaks-in-lists
• mkdocstrings Anchors (autorefs)
• mkdocstrings Cross-References
• Python Markdown "Abbreviations"*
  • *Note: the markup (HTML) rendered for abbreviations is not useful for rendering. If important, I'm open to contributions because the implementation could be challenging
• Python Markdown "Attribute Lists"
  • Preserves attribute list syntax when using --wrap mode
• PyMdown Extensions "Arithmatex" (Math/LaTeX Support) (Material for MkDocs Math)
  • This plugin combines three math rendering plugins from mdit-py-plugins:
    1. dollarmath: Handles $...$ (inline) and $$...$$ (block) with smart dollar mode that prevents false positives (e.g., $3.00 is not treated as math)
    2. texmath: Handles \(...\) (inline) and \[...\] (block) LaTeX bracket notation
    3. amsmath: Handles LaTeX environments like \begin{align}...\end{align}, \begin{cases}...\end{cases}, \begin{matrix}...\end{matrix}, etc.
  • Can be deactivated entirely with the --no-mkdocs-math flag
• Python Markdown "Snippets"*
  • *Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets

Features with Implicit Support

The following MkDocs/Material/PyMdown syntax passes through mdformat-mkdocs unchanged — it is not modified or corrupted, but it is also not actively normalized:

• PyMdown Keys — ++ctrl+alt+del++ (not a markdown construct, preserved as-is)
• PyMdown Critic Markup — {--deleted--}, {++added++}, {~~old~>new~~}, {==highlight==}, {>>comment<<}
• PyMdown Highlight — ==marked text==
• PyMdown Caret / Tilde — H^2^O, CH~3~OH
• PyMdown Emoji — :smile:, :material-icon:
• PyMdown InlineHilite — language hints inside backtick spans (:::python code) are never modified
• PyMdown SmartSymbols — (c), (tm), --, --> are plain ASCII in source and not touched
• PyMdown MagicLink — @username, #123 are plain text and pass through
• Material Grids — <div class="grid cards" markdown> is an HTML block; content is preserved but markdown inside is not reformatted
• Mermaid / Superfences — diagram code inside fenced blocks is never modified

Note on PyMdown ProgressBar: The syntax [=50% "50%"] resembles an undefined link reference and will be escaped to \[=50% "50%"\] by default. Use --ignore-missing-references to preserve it, or avoid this extension if you use mdformat without that flag.

See the example test files, ./tests/pre-commit-test.md and ./tests/format/fixtures.md

mdformat Usage

Add this package wherever you use mdformat and the plugin will be auto-recognized. No additional configuration necessary. For additional information on plugins, see the official mdformat documentation here

Optional Extras

This package specifies two optional "extra" plugins ('recommended' and 'recommended-mdsf' ) for plugins that work well with typical documentation managed by mkdocs:

• For 'recommended':
  • mdformat-beautysh
  • mdformat-config
  • mdformat-footnote
  • mdformat-front-matters (previously mdformat-frontmatter)
  • mdformat-gfm
  • mdformat-ruff
  • mdformat-simple-breaks
  • mdformat-web
  • mdformat-wikilink
• For 'recommended-mdsf':
  • Instead of mdformat-beautysh, mdformat-config, mdformat-ruff, and mdformat-web, the "mdsf" extras install mdformat-hooks, which allows the use of mdsf for formatting code blocks in hundreds of languages using CLI formatters you already have installed; however, this requires extra configuration, so make sure to see the README: https://github.com/KyleKing/mdformat-hooks

pre-commit/prek

repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 1.0.0
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-mkdocs
          # Or
          # - "mdformat-mkdocs[recommended-mdsf]>=5.2.2"
          # Or
          # - "mdformat-mkdocs[recommended]>=5.2.2"

uvx

uvx --with=mdformat-mkdocs mdformat

Or with pipx:

pipx install mdformat
pipx inject mdformat mdformat-mkdocs

HTML Rendering

To generate HTML output, any of the plugins can be imported from mdit_plugins. For more guidance on MarkdownIt, see the docs: https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser

from markdown_it import MarkdownIt

from mdformat_mkdocs.mdit_plugins import (
    material_admon_plugin,
    material_content_tabs_plugin,
    mkdocstrings_autorefs_plugin,
    mkdocstrings_crossreference_plugin,
    pymd_abbreviations_plugin,
)

md = MarkdownIt()
md.use(material_admon_plugin)
md.use(material_content_tabs_plugin)
md.use(mkdocstrings_autorefs_plugin)
md.use(mkdocstrings_crossreference_plugin)
md.use(pymd_abbreviations_plugin)

text = "- Line 1\n    - `bash command`\n    - Line 3"
md.render(text)
# <ul>
# <li>Line 1
# <ul>
# <li><code>bash command</code></li>
# <li>Line 3</li>
# </ul>
# </li>
# </ul>

Configuration

mdformat-mkdocs adds the CLI arguments:

• --align-semantic-breaks-in-lists to optionally align semantic line breaks (continuation lines that aren't a nested list, code block, or admonition) to the width of the list marker: 3-spaces for numbered lists, 2-spaces for bulleted lists. If not specified, the default of 4-indents is followed universally.

  # with: mdformat
  1. Semantic line feed where the following line is
      three spaces deep
  
  - Semantic line feed where the following line is
      two spaces deep
  
  # vs. "mdformat --align-semantic-breaks-in-lists"
  1. Semantic line feed where the following line is
     three spaces deep
  
  - Semantic line feed where the following line is
    two spaces deep
  

• --ignore-missing-references if set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings

• --no-mkdocs-math if set, deactivate math/LaTeX rendering (Arithmatex). By default, math is enabled. This can be useful if you want to format markdown without processing math syntax.

You can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):

# .mdformat.toml

[plugin.mkdocs]
align_semantic_breaks_in_lists = true
ignore_missing_references = true
no_mkdocs_math = true

Contributing

See CONTRIBUTING.md