CommonMark compliant Markdown formatter
Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. Mdformat is a Unix-style command-line tool as well as a Python library.
The features/opinions of the formatter include:
- Consistent indentation and whitespace across the board
- Always use ATX style headings
- Move all link references to the bottom of the document (sorted by label)
- Reformat indented code blocks as fenced code blocks
- Use
1.
as the ordered list marker if possible, also for noninitial list items
Mdformat by default will not change word wrapping. The rationale for this is to support Semantic Line Breaks.
For a comprehensive description and rationalization of the style, read the style guide.
NOTE: The formatting style produced by mdformat may change in each version. It is recommended to pin mdformat dependency version.
Mdformat also offers an extensible plugin system for both code fence content formatting and parser extensions (like tables).
pip install mdformat
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 -
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.
foo@bar:~$ mdformat --help
usage: mdformat [-h] [--check] [--version] [--number] [paths [paths ...]]
CommonMark compliant Markdown formatter
positional arguments:
paths files to format
optional arguments:
-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
import mdformat
unformatted = "\n\n# A header\n\n"
formatted = mdformat.text(unformatted)
assert formatted == "# A header\n"
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)
Any options available in the CLI are also available in the Python API, with equivalent option names.
For instance, to switch on consecutive numbering of ordered lists, do
import mdformat
mdformat.file("FILENAME.md", options={"number": True})
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.5.3 # Use the ref you want to point at
hooks:
- id: mdformat
# optional
additional_dependencies:
- mdformat-tables
- mdformat-black
Mdformat features a plugin system to support formatting of Markdown code blocks where the coding language has been labeled.
For instance, if mdformat-black
plugin is installed in the environment,
mdformat CLI will automatically format Python code blocks with Black.
For stability, mdformat Python API behavior will not change simply due to a plugin being installed. Code formatters will have to be explicitly enabled in addition to being installed:
import mdformat
unformatted = "```python\n'''black converts quotes'''\n```\n"
# Pass in `codeformatters` here! It is an iterable of coding languages
# that should be formatted
formatted = mdformat.text(unformatted, codeformatters={"python"})
assert formatted == '```python\n"""black converts quotes"""\n```\n'
Read the contribution guide if you wish to implement a new code formatter plugin.
Plugin | Supported languages |
---|---|
mdformat-beautysh | bash , sh |
mdformat-black | python |
mdformat-config | json , toml , yaml |
mdformat-gofmt | go |
mdformat-web | javascript , js , css , html , xml |
Markdown-it-py offers a range of useful extensions to the base CommonMark parser (see the documented list).
Mdformat features a plugin system to support the loading and rendering of such extensions.
For stability, mdformat Python API behavior will not change simply due to a plugin being installed. Extensions will have to be explicitly enabled in addition to being installed:
import mdformat
unformatted = "content...\n"
# Pass in `extensions` here! It is an iterable of extensions that should be loaded
formatted = mdformat.text(unformatted, extensions={"tables"})
Read the contribution guide if you wish to implement a new parser extension plugin.
Plugin | Syntax Extensions | Description |
---|---|---|
mdformat-gfm | gfm |
Changes target specification to GitHub Flavored Markdown (GFM) |
mdformat-tables | tables |
Adds support for GitHub Flavored Markdown style tables |
mdformat-toc | toc |
Adds the capability to auto-generate a table of contents |