Package: mdformat
CommonMark compliant Markdown formatterMdformat 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 thedocs.InstallingInstall withCommonMarksupport:pipinstallmdformatInstall withGitHub Flavored Markdown (GFM)support:pipinstallmdformat-gfmNote that GitHub's Markdown renderer supports syntax extensions not included in the GFM specification.
For full GitHub support do:pipinstallmdformat-gfmmdformat-frontmattermdformat-footnoteInstall withMarkedly Structured Text (MyST)support:pipinstallmdformat-mystCommand line usageFormat filesFormat filesREADME.mdandCHANGELOG.mdin placemdformatREADME.mdCHANGELOG.mdFormat.mdfiles in current working directory recursivelymdformat.Read Markdown from standard input untilEOF.
Write formatted Markdown to standard output.mdformat-Check formattingmdformat--checkREADME.mdCHANGELOG.mdThis will not apply any changes to the files.
If a file is not properly formatted, the exit code will be non-zero.Optionsfoo@bar:~$mdformat--helpusage: mdformat [-h] [--check] [--version] [--number] [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}] [paths ...]CommonMark compliant Markdown formatterpositional arguments:paths                 files to formatoptions:-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)DocumentationThis README merely provides a quickstart guide for the command line interface.
For more information refer to thedocumentation.
Here's a few pointers to get you started:Style guidePython API usageUsage as a pre-commit hookPlugin usagePlugin development guideList of code block formatter pluginsList of parser extension pluginsChangelogFrequently Asked QuestionsWhy not usePrettierinstead?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 withpre-commit(also Python).
Prettier on the other hand requires Node.js/npm.Prettier suffers fromnumerousbugs,
many of which cause changes in Markdown AST and rendered HTML.
Many of these bugs are a consequence of usingremark-parsev8.x as Markdown parser which,
according to the author themselves,
isinferior to markdown-itused by mdformat.remark-parsev9.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 likeautomatic 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 😄.