CommonMark compliant Markdown formatter
Project description
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.
Find out more in the docs.
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
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}] [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
--wrap {keep,no,INTEGER}
paragraph word wrap mode (default: keep)
--end-of-line {lf,crlf}
output file line ending mode (default: lf)
Documentation
This README merely provides a quickstart guide for the command line interface. For more information refer to the documentation. Here's a few pointers to get you started:
- Style guide
- Python API usage
- Usage as a pre-commit hook
- Plugin usage
- Plugin development guide
- List of code block formatter plugins
- List of parser extension plugins
- Changelog
Frequently Asked Questions
Why not use Prettier instead?
Mdformat is pure Python code! Python is pre-installed on macOS and virtually any Linux distribution, meaning that typically little to no additional installations are required to run mdformat. This argument also holds true when using together with pre-commit (also Python). Prettier on the other hand requires Node.js/npm.
Prettier suffers from
numerous
bugs,
many of which cause changes in Markdown AST and rendered HTML.
Many of these bugs are a consequence of using
remark-parse
v8.x as Markdown parser which,
according to the author themselves,
is inferior to markdown-it used by mdformat.
remark-parse v9.x is advertised as CommonMark compliant
and presumably would fix many of the issues,
but is not used by Prettier (v2.4.0) yet.
Prettier (v2.4.0), being able to format many languages other than Markdown, is a large package with 65 direct dependencies (mdformat only has one in Python 3.11+). This can be a disadvantage in many environments, one example being size optimized Docker images.
Mdformat's parser extension plugin API allows not only customization of the Markdown specification in use, but also advanced features like automatic table of contents generation. Also provided is a code formatter plugin API enabling integration of embedded code formatting for any programming language.
What's wrong with the mdformat logo? It renders incorrectly and is just terrible in general.
Nope, the logo is actually pretty great – you're terrible. The logo is more a piece of art than a logo anyways, depicting the horrors of poorly formatted text documents. I made it myself!
That said, if you have any graphic design skills and want to contribute a revised version, a PR is more than welcome 😄.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file mdformat-0.7.14.tar.gz.
File metadata
- Download URL: mdformat-0.7.14.tar.gz
- Upload date:
- Size: 27.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.7.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 60c457955f795e5a030e24bc96be30a29eee7836ba98b32e02581688da7670c5 |
|
| MD5 | 4491596af111e542d3acd6282dd858ae |
|
| BLAKE2b-256 | 1ce7a6d1f652d20cea7e676799ebbee3da86dae8a4a6bdc20a89a823b6921421 |
File details
Details for the file mdformat-0.7.14-py3-none-any.whl.
File metadata
- Download URL: mdformat-0.7.14-py3-none-any.whl
- Upload date:
- Size: 28.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/34.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.63.0 importlib-metadata/4.11.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.7.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 530eabe496726bd5f4dec5635c37c2496f4c8abc4c15fafa606919b48d92a9d9 |
|
| MD5 | c5aca455c504d0167c6181bd56f6848a |
|
| BLAKE2b-256 | 795e78755d623a4bc7b56d39f94e0846033afeb03dcbd6b927c19c36430c5579 |
