mdformat#

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 will not change word wrapping by default. The rationale for this is to support Semantic Line Breaks.

For a comprehensive description and rationalization of the style, read the style guide.

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 😄.