Installation and usage#

Installing#

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

Warning

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 README.md and CHANGELOG.md in place

mdformat README.md CHANGELOG.md

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 README.md CHANGELOG.md

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

Options#

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

options:
  -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 README.md in place:

import mdformat

# Input filepath as a string...
mdformat.file("README.md")

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

filepath = pathlib.Path("README.md")
mdformat.file(filepath)

Options#

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

import mdformat

mdformat.file(
    "FILENAME.md",
    options={
        "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: https://github.com/executablebooks/mdformat
  rev: 0.7.16  # Use the ref you want to point at
  hooks:
  - id: mdformat
    # Optionally add plugins
    additional_dependencies:
    - mdformat-gfm
    - mdformat-black