Installation and usage#


Install with CommonMark support:

pip install mdformat

Install with GitHub Flavored Markdown (GFM) support:

pip install mdformat-gfm

Note that GitHub’s Markdown renderer supports syntax extensions not included in the GFM specification. For full GitHub support do:

pip install mdformat-gfm mdformat-frontmatter mdformat-footnote

Install with Markedly Structured Text (MyST) support:

pip install mdformat-myst


The formatting style produced by mdformat may change in each version. It is recommended to pin mdformat dependency version.

Command line usage#

Format files#

Format files and in place


Format .md files in current working directory recursively

mdformat .

Read Markdown from standard input until EOF. Write formatted Markdown to standard output.

mdformat -

Check formatting#

mdformat --check

This will not apply any changes to the files. If a file is not properly formatted, the exit code will be non-zero.


foo@bar:~$ mdformat --help
usage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]

CommonMark compliant Markdown formatter

positional arguments:
  paths                 files to format

  -h, --help            show this help message and exit
  --check               do not apply changes to files
  --version             show program's version number and exit
  --number              apply consecutive numbering to ordered lists
  --wrap {keep,no,INTEGER}
                        paragraph word wrap mode (default: keep)
  --end-of-line {lf,crlf,keep}
                        output file line ending mode (default: lf)

Python API usage#

Format text#

import mdformat

unformatted = "\n\n# A header\n\n"
formatted = mdformat.text(unformatted)
assert formatted == "# A header\n"

Format a file#

Format file in place:

import mdformat

# Input filepath as a string...

# ...or a pathlib.Path object
import pathlib

filepath = pathlib.Path("")


All formatting style modifying options available in the CLI are also available in the Python API, with equivalent option names:

import mdformat

        "number": True,  # switch on consecutive numbering of ordered lists
        "wrap": 60,  # set word wrap width to 60 characters

Usage as a pre-commit hook#

mdformat can be used as a pre-commit hook. Add the following to your project’s .pre-commit-config.yaml to enable this:

- repo:
  rev: 0.7.16  # Use the ref you want to point at
  - id: mdformat
    # Optionally add plugins
    - mdformat-gfm
    - mdformat-black