--- id: mdformat-mkdocs version: "5.3.0" license: MIT license_treatment: permissive maintenance: active --- # mdformat-mkdocs — An mdformat plugin for mkdocs and Material for MkDocs License: permissive · Maintenance: active · Downloads: 158.2K/mo ## 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 above — 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 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 - License: MIT (permissive) - Python support: supports_current - Install friction: low - Maintenance: active - Downloads: 158.2K/month (top 15,000 on PyPI) - Known vulnerabilities: none known ## Tags mdformat plugin mkdocs, markdown formatter mkdocs material, format markdown for documentation, mkdocs syntax aware formatter, markdown linter mkdocs, admonition content tabs formatter, documentation markdown standardization, mkdocs-plugin, markdown-formatter, documentation-tooling [View on SkillFed](https://skillfed.io/packages/mdformat-mkdocs) · [View on PyPI](https://pypi.org/project/mdformat-mkdocs/)