mdformat

1.0.0 · active · verified Fri Apr 10

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.

Warnings

breaking mdformat 1.0.0 removed official support for Python 3.9. Users should upgrade to Python 3.10 or newer.
Fix: Upgrade your Python environment to version 3.10 or later.
gotcha 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.
Fix: Pin the `mdformat` version in your `requirements.txt` or `pyproject.toml` (e.g., `mdformat==1.0.0`).
gotcha `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`).
Fix: Install and configure specific `mdformat` plugins (e.g., `pip install mdformat-gfm`) to handle non-CommonMark syntax extensions.
breaking 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.
Fix: Update custom plugins to conform to the latest plugin API, or check for updated versions of third-party plugins.
gotcha `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.
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.
gotcha 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.
Fix: Install a plugin like `mdformat-simple-breaks` if you prefer a different style for thematic breaks.

Install

pip install mdformat Install with CommonMark support
pip install mdformat mdformat-gfm Install with GitHub Flavored Markdown (GFM) support (via plugin)
pipx install mdformat Recommended global installation (for CommonMark)

Imports

mdformat
```
import mdformat
```

Quickstart

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.

import mdformat

unformatted_markdown = """
# A Header

This is some **unformatted**  text.

- List item 1
- List item 2

"""

formatted_markdown = mdformat.text(unformatted_markdown)

print("--- Unformatted ---")
print(unformatted_markdown)
print("\n--- Formatted ---")
print(formatted_markdown)

# Example with options
formatted_with_options = mdformat.text(
    "- One\n- Two\n- Three",
    options={
        "number": True, # Apply consecutive numbering to ordered lists
        "wrap": 60      # Set word wrap width to 60 characters
    }
)
print("\n--- Formatted with Options ---")
print(formatted_with_options)

# To format a file in place (requires a file to exist):
# with open("test.md", "w") as f:
#     f.write(unformatted_markdown)
# mdformat.file("test.md")
# with open("test.md", "r") as f:
#     print("\n--- Formatted File ---")
#     print(f.read())

view raw JSON →