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
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:
mdformat-tables: Adds support for Github Flavored Markdown style tables.
mdformat-frontmatter: Adds support for the yaml header with metadata of the file.
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
These are the functionalities I miss when writing markdown that can be currently fixed with
- 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:
- Links are sent to the bottom of the document.
- Do typographic replacements
- End paragraphs with a dot.
Developing mdformat plugins⚑
There are two kinds of plugins:
- Formatters: They change the output of the text. For example
- Parsers: They are extensions to the base CommonMark parser.
You can see some plugin examples here.
- It doesn't yet support admonitions
- You can't ignore some files, nor some part of the file