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.17 # Use the ref you want to point at
hooks:
- id: mdformat
# Optionally add plugins
additional_dependencies:
- mdformat-gfm
- mdformat-black