Registry / devops / mdformat-mkdocs

mdformat-mkdocs

library5.1.4pypypiunverified

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.

devops web-framework serialization

pip install mdformat-mkdocs

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · MDFORMAT-MKDOCS

mdformat-mkdocs

devopspythonv5.1.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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. #

mdformat --version

Debug

Known issues

breakingmdformat-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`.

affects: mdformat-mkdocs >= 5.0.0 (requires mdformat >= 0.17.0)

gotchaThe `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`.

affects: All versions

gotchaUpdating `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`).

affects: mdformat >= 0.17.0 (when upgrading from older mdformat versions)

Errors

Common errors & fixes

mdformat: error: argument --plugins: invalid choice: 'mkdocs' (choose from 'gfm', 'myst')

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.

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'

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.

Upgrade

Version history

5.1.4latest on PyPI · released Jan 26, 2026

Audit

Dependencies

mdformatrequiredThis package is an mdformat plugin and requires mdformat to function. It specifically requires mdformat>=0.17.0.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/kyleking/mdformat-mkdocs ↗

packagehttps://pypi.org/project/mdformat-mkdocs/ ↗

changeloghttps://github.com/kyleking/mdformat-mkdocs/releases ↗