{"id":2584,"library":"mdformat","title":"mdformat","description":"Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. It functions as both a Unix-style command-line tool and a Python library. The current stable version is 1.0.0, and it features an extensible plugin system to support various Markdown extensions and embedded code formatting. The project maintains an active release cadence, with version 1.0.0 released after several minor versions, indicating ongoing development and maintenance.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/hukkin/mdformat","tags":["formatter","markdown","commonmark","cli","linter","pre-commit","plugin","style-guide"],"install":[{"cmd":"pip install mdformat","lang":"bash","label":"Install with CommonMark support"},{"cmd":"pip install mdformat mdformat-gfm","lang":"bash","label":"Install with GitHub Flavored Markdown (GFM) support (via plugin)"},{"cmd":"pipx install mdformat","lang":"bash","label":"Recommended global installation (for CommonMark)"}],"dependencies":[{"reason":"Core Markdown parser dependency.","package":"markdown-it-py","optional":false},{"reason":"Optional plugin to add GitHub Flavored Markdown support.","package":"mdformat-gfm","optional":true},{"reason":"Optional plugin to enable configuration via pyproject.toml.","package":"mdformat-pyproject","optional":true},{"reason":"Optional plugin to format Python code blocks using Black.","package":"mdformat-black","optional":true}],"imports":[{"symbol":"mdformat","correct":"import mdformat"}],"quickstart":{"code":"import mdformat\n\nunformatted_markdown = \"\"\"\n# A Header\n\nThis is some **unformatted**  text.\n\n- List item 1\n- List item 2\n\n\"\"\"\n\nformatted_markdown = mdformat.text(unformatted_markdown)\n\nprint(\"--- Unformatted ---\")\nprint(unformatted_markdown)\nprint(\"\\n--- Formatted ---\")\nprint(formatted_markdown)\n\n# Example with options\nformatted_with_options = mdformat.text(\n    \"- One\\n- Two\\n- Three\",\n    options={\n        \"number\": True, # Apply consecutive numbering to ordered lists\n        \"wrap\": 60      # Set word wrap width to 60 characters\n    }\n)\nprint(\"\\n--- Formatted with Options ---\")\nprint(formatted_with_options)\n\n# To format a file in place (requires a file to exist):\n# with open(\"test.md\", \"w\") as f:\n#     f.write(unformatted_markdown)\n# mdformat.file(\"test.md\")\n# with open(\"test.md\", \"r\") as f:\n#     print(\"\\n--- Formatted File ---\")\n#     print(f.read())\n","lang":"python","description":"This quickstart demonstrates how to use `mdformat.text()` to format a Markdown string directly. It also shows how to apply formatting options like numbering ordered lists and setting word wrap width. For file-based formatting, `mdformat.file()` can be used, which modifies the file in place."},"warnings":[{"fix":"Upgrade your Python environment to version 3.10 or later.","message":"mdformat 1.0.0 removed official support for Python 3.9. Users should upgrade to Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Pin the `mdformat` version in your `requirements.txt` or `pyproject.toml` (e.g., `mdformat==1.0.0`).","message":"The exact formatting style produced by `mdformat` is not guaranteed to be stable across major or even minor versions. It is highly recommended to pin the `mdformat` dependency version in your project to ensure consistent formatting.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install and configure specific `mdformat` plugins (e.g., `pip install mdformat-gfm`) to handle non-CommonMark syntax extensions.","message":"`mdformat` is a CommonMark formatter by default. It may backslash-escape syntax extensions (e.g., GitHub Flavored Markdown, MkDocs, Hugo) that are not part of the CommonMark specification to ensure formatting changes do not alter the rendered document. For proper formatting of extended Markdown, install and enable relevant plugins (e.g., `mdformat-gfm`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update custom plugins to conform to the latest plugin API, or check for updated versions of third-party plugins.","message":"The plugin API has undergone changes, specifically in version 1.0.0. For instance, `mdformat.plugins.ParserExtensionInterface.add_cli_options` was removed (deprecated since 0.7.19) and replaced by `mdformat.plugins.ParserExtensionInterface.add_cli_argument_group`. Plugins developed for older versions might break.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If you are confident the formatting is safe, use `mdformat --no-validate` on the CLI or `mdformat.text(..., validate=False)` in the API. Report the issue if it's a bug in `mdformat` or a plugin.","message":"`mdformat` includes a safety check that errors if the formatted Markdown renders to different HTML than the input Markdown (`Formatted Markdown renders to different HTML than input Markdown`). While this protects against accidental content changes, it can sometimes trigger false positives, especially with certain plugins or complex Markdown. The `--no-validate` CLI option or `validate=False` API option can disable this check.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install a plugin like `mdformat-simple-breaks` if you prefer a different style for thematic breaks.","message":"By default, thematic breaks (horizontal rules) are formatted as a 70-character wide string of underscores. If a different style (e.g., `---`) is desired, a specific plugin like `mdformat-simple-breaks` is required.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}