Skip to content

mdformat

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.

It's based on the markdown-it-py Markdown parser, which is a Python implementation of markdown-it.

Installation⚑

By default it uses CommonMark support:

pip install mdformat

This won't support task lists, if you want them use the github flavoured parser instead:

pip install mdformat-gfm

You may want to also install some interesting plugins:

To install them with pipx you can run:

pipx install --include-deps mdformat-gfm
pipx inject mdformat-gfm mdformat-beautysh mdformat-black mdformat-config \
    mdformat-web mdformat-tables mdformat-frontmatter

Desires⚑

These are the functionalities I miss when writing markdown that can be currently fixed with mdformat:

  • Long lines are wrapped.
  • Long lines in lists are wrapped and the indentation is respected.
  • Add correct blank lines between sections.

I haven't found yet a way to achieve:

Developing mdformat plugins⚑

There are two kinds of plugins:

  • Formatters: They change the output of the text. For example mdformatormat-black.
  • Parsers: They are extensions to the base CommonMark parser.

You can see some plugin examples here.

Issues⚑

References⚑