mdformat-mkdocs Plugin for MkDocs Formatting

5.1.4 · active · verified Fri Apr 17

mdformat-mkdocs is an mdformat plugin designed to format Markdown files specifically tailored for MkDocs and Material for MkDocs. It handles features like blockquote directives (admonitions) and other MkDocs-specific syntax, ensuring consistent styling when used with the `mdformat` CLI tool. It is actively maintained and generally follows the release cadence of its host library, `mdformat`, releasing updates as needed to maintain compatibility and add features.

Common errors

```
mdformat: error: argument --plugins: invalid choice: 'mkdocs' (choose from 'gfm', 'myst')
```
cause The `mdformat-mkdocs` package is not installed or `mdformat` cannot find the plugin.

fix Ensure `mdformat-mkdocs` is correctly installed in your environment: `pip install mdformat-mkdocs`. If using a virtual environment, ensure it's activated.
```
MkDocs-specific syntax (e.g., admonitions, directives) is not formatted by mdformat.
```
cause The `mkdocs` plugin has been installed but not enabled for the current `mdformat` run.

fix Enable the plugin via the CLI (`mdformat --plugins mkdocs your_file.md`) or in `pyproject.toml` (`[tool.mdformat] plugins = ["mkdocs"]`).
```
ModuleNotFoundError: No module named 'mdformat_mkdocs'
```
cause The `mdformat-mkdocs` package is not installed or is not accessible in the Python environment where `mdformat` is running.

fix Install `mdformat-mkdocs`: `pip install mdformat-mkdocs`. If in a virtual environment, ensure it's activated before installation.

Warnings

breaking mdformat-mkdocs version 5.0.0 and newer requires mdformat version 0.17.0 or higher. Using an older version of mdformat will lead to `ModuleNotFoundError` or incorrect plugin behavior.
Fix: Ensure your `mdformat` installation is up-to-date: `pip install --upgrade mdformat mdformat-mkdocs`.
gotcha The `mkdocs` plugin must be explicitly enabled when running `mdformat`, either via the `--plugins mkdocs` CLI argument or by configuring it in `pyproject.toml`.
Fix: Add `--plugins mkdocs` to your `mdformat` command: `mdformat --plugins mkdocs your_file.md` or add `plugins = ["mkdocs"]` under `[tool.mdformat]` in your `pyproject.toml`.
gotcha Updating `mdformat-mkdocs` can sometimes pull in a new major version of its dependency, `mdformat`. `mdformat` 0.17.0 introduced significant changes to default code styling, particularly regarding line wrapping. This might cause more extensive formatting changes than anticipated.
Fix: Review `mdformat`'s changelog, especially for major version bumps. If specific formatting styles are desired, configure them in `pyproject.toml` using `mdformat`'s style options (e.g., `wrap = "keep"`, `number = true`).

Install

pip install mdformat-mkdocs Install latest version

Quickstart

This quickstart demonstrates how to install `mdformat-mkdocs` and use it to format a Markdown file with MkDocs-specific syntax, such as admonitions. The `mdformat` command-line tool is used, and the `--plugins mkdocs` argument explicitly enables the plugin. The example shows how to format a file and then read its content, as `mdformat` typically modifies files in-place.

# 1. Install mdformat-mkdocs
pip install mdformat-mkdocs

# 2. Create an example Markdown file (e.g., 'docs/index.md')
with open('docs/index.md', 'w') as f:
    f.write('## My Doc\n\n!!! note "Hello"\n    This is a note.\n\n<p>Some HTML comment</p>\n')

# 3. Format the file using mdformat with the mkdocs plugin
#    (Note: The 'docs' directory must exist for the file to be created)
import os
if not os.path.exists('docs'):
    os.makedirs('docs')

# Using a subprocess call as mdformat is primarily a CLI tool
import subprocess
result = subprocess.run(['mdformat', '--plugins', 'mkdocs', 'docs/index.md'], capture_output=True, text=True)

# Print the formatted content (mdformat modifies the file in place by default)
with open('docs/index.md', 'r') as f:
    formatted_content = f.read()

print("--- Original (before format) ---")
print("## My Doc\n\n!!! note \"Hello\"\n    This is a note.\n\n<p>Some HTML comment</p>\n")
print("\n--- Formatted Content ---")
print(formatted_content)

# Expected output for the admonition and blank line removal
# Note: mdformat applies its own default styles too
# Expected: 
# ## My Doc
#
# !!! note "Hello"
#     This is a note.
# <!-- Some HTML comment -->

view raw JSON →