mdformat-mkdocs

What it is and what it does

mdformat-mkdocs is a plugin for the mdformat Markdown formatter that adds awareness of MkDocs-specific and Material for MkDocs syntax. It standardizes Markdown formatting (four-space indents, dash-based unordered lists, single-digit ordered list markers by default) while preserving or actively formatting MkDocs extensions like admonitions, content tabs, definition lists, mkdocstrings injection blocks and cross-references, and math notation via dollarmath, texmath, and amsmath.

The plugin integrates seamlessly into any mdformat workflow—it auto-registers and requires no configuration. It handles both explicit formatting (admonitions with extra spacing for consistency with mkdocs styleguide, math block normalization) and implicit pass-through of PyMdown extensions like emoji, critic markup, and inline highlighting. It also supports optional extras for recommended companion formatters and provides flags like --no-mkdocs-math to disable math formatting and --ignore-missing-references to preserve ProgressBar syntax.

Use it for:

• Format documentation projects using MkDocs Material with consistent indentation and list styles across all Markdown files.
• Normalize admonitions, content tabs, and definition lists in Material for MkDocs docs while preserving their semantic meaning.
• Standardize math notation (LaTeX and dollar-sign blocks) in technical documentation built with MkDocs.
• Integrate into pre-commit hooks or CI pipelines to enforce Markdown style consistency for mkdocs-based projects.
• Preserve mkdocstrings injection blocks and cross-references during automated Markdown reformatting.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An mdformat plugin that formats Markdown for MkDocs projects, handling MkDocs-specific syntax like admonitions, content tabs, definition lists, and math notation while standardizing indentation and list formatting.

Yes. Active maintenance, no vulnerabilities, low install friction, and permissive MIT license make this a safe choice. Install it if you format Markdown in MkDocs or Material for MkDocs projects and want a formatter that understands your project's syntax without corrupting extensions. Skip it if you don't use MkDocs or have no need for automated Markdown formatting.

Install

mdformat-mkdocs on PyPI

pip install mdformat-mkdocs

uv add mdformat-mkdocs

poetry add mdformat-mkdocs

Installing mdformat-mkdocs

Before you install

Low friction install with four runtime dependencies (mdformat, mdformat-gfm, mdit-py-plugins, more-itertools). Active maintenance with a release 12 days ago and no known vulnerabilities.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects.

Quickstart

pip install mdformat-mkdocs

# mdformat-mkdocs auto-registers as an mdformat plugin
mdformat your_docs.md

# Or with options:
mdformat --number your_docs.md  # Apply consecutive numbering to ordered lists

Requires Python 3.10.0 or later.

Verify before relying

• Whether the package handles all edge cases in nested mkdocstrings injection blocks with --align-semantic-breaks-in-lists
• Performance characteristics when formatting large documentation projects
• Compatibility with custom MkDocs extensions beyond those explicitly listed

Package facts

Evidence: mdformat_mkdocs-5.3.0-py3-none-any.whl

Keywords: markdown, markdown-it, mdformat, mdformat_plugin_template

Tags

More Python Modules packages