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