{"id":9930,"library":"mdformat-mkdocs","title":"mdformat-mkdocs Plugin for MkDocs Formatting","description":"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.","status":"active","version":"5.1.4","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/mdformat-mkdocs","tags":["markdown","formatting","mkdocs","material-for-mkdocs","mdformat","plugin","admonitions"],"install":[{"cmd":"pip install mdformat-mkdocs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package is an mdformat plugin and requires mdformat to function. It specifically requires mdformat>=0.17.0.","package":"mdformat","optional":false}],"imports":[],"quickstart":{"code":"# 1. Install mdformat-mkdocs\npip install mdformat-mkdocs\n\n# 2. Create an example Markdown file (e.g., 'docs/index.md')\nwith open('docs/index.md', 'w') as f:\n    f.write('## My Doc\\n\\n!!! note \"Hello\"\\n    This is a note.\\n\\n<p>Some HTML comment</p>\\n')\n\n# 3. Format the file using mdformat with the mkdocs plugin\n#    (Note: The 'docs' directory must exist for the file to be created)\nimport os\nif not os.path.exists('docs'):\n    os.makedirs('docs')\n\n# Using a subprocess call as mdformat is primarily a CLI tool\nimport subprocess\nresult = subprocess.run(['mdformat', '--plugins', 'mkdocs', 'docs/index.md'], capture_output=True, text=True)\n\n# Print the formatted content (mdformat modifies the file in place by default)\nwith open('docs/index.md', 'r') as f:\n    formatted_content = f.read()\n\nprint(\"--- Original (before format) ---\")\nprint(\"## My Doc\\n\\n!!! note \\\"Hello\\\"\\n    This is a note.\\n\\n<p>Some HTML comment</p>\\n\")\nprint(\"\\n--- Formatted Content ---\")\nprint(formatted_content)\n\n# Expected output for the admonition and blank line removal\n# Note: mdformat applies its own default styles too\n# Expected: \n# ## My Doc\n#\n# !!! note \"Hello\"\n#     This is a note.\n# <!-- Some HTML comment -->","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your `mdformat` installation is up-to-date: `pip install --upgrade mdformat mdformat-mkdocs`.","message":"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.","severity":"breaking","affected_versions":"mdformat-mkdocs >= 5.0.0 (requires mdformat >= 0.17.0)"},{"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`.","message":"The `mkdocs` plugin must be explicitly enabled when running `mdformat`, either via the `--plugins mkdocs` CLI argument or by configuring it in `pyproject.toml`.","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"mdformat >= 0.17.0 (when upgrading from older mdformat versions)"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `mdformat-mkdocs` is correctly installed in your environment: `pip install mdformat-mkdocs`. If using a virtual environment, ensure it's activated.","cause":"The `mdformat-mkdocs` package is not installed or `mdformat` cannot find the plugin.","error":"mdformat: error: argument --plugins: invalid choice: 'mkdocs' (choose from 'gfm', 'myst')"},{"fix":"Enable the plugin via the CLI (`mdformat --plugins mkdocs your_file.md`) or in `pyproject.toml` (`[tool.mdformat]\nplugins = [\"mkdocs\"]`).","cause":"The `mkdocs` plugin has been installed but not enabled for the current `mdformat` run.","error":"MkDocs-specific syntax (e.g., admonitions, directives) is not formatted by mdformat."},{"fix":"Install `mdformat-mkdocs`: `pip install mdformat-mkdocs`. If in a virtual environment, ensure it's activated before installation.","cause":"The `mdformat-mkdocs` package is not installed or is not accessible in the Python environment where `mdformat` is running.","error":"ModuleNotFoundError: No module named 'mdformat_mkdocs'"}]}