Skip to main content

CommonMark compliant Markdown formatter

Project description

Documentation Status Build Status codecov.io PyPI version

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.

Find out more in the docs.

Installing

Install with CommonMark support:

pipx install mdformat

Install with GitHub Flavored Markdown (GFM) support:

pipx install mdformat
pipx inject mdformat mdformat-gfm

Note that GitHub's Markdown renderer supports syntax extensions not included in the GFM specification. For full GitHub support do:

pipx install mdformat
pipx inject mdformat mdformat-gfm mdformat-frontmatter mdformat-footnote mdformat-gfm-alerts

Install with Markedly Structured Text (MyST) support:

pipx install mdformat
pipx inject mdformat 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] [--no-validate] [--version] [--number]
                [--wrap {keep,no,INTEGER}] [--end-of-line {lf,crlf,keep}]
                [--exclude PATTERN] [--extensions EXTENSION]
                [--codeformatters LANGUAGE]
                [paths ...]

CommonMark compliant Markdown formatter

positional arguments:
  paths                 files to format

options:
  -h, --help            show this help message and exit
  --check               do not apply changes to files
  --no-validate         do not validate that the rendered HTML is consistent
  --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)
  --exclude PATTERN     exclude files that match the Unix-style glob pattern
                        (multiple allowed)
  --extensions EXTENSION
                        require and enable an extension plugin (multiple
                        allowed) (use `--no-extensions` to disable) (default:
                        all enabled)
  --codeformatters LANGUAGE
                        require and enable a code formatter plugin (multiple
                        allowed) (use `--no-codeformatters` to disable)
                        (default: all enabled)

The --exclude option is only available on Python 3.13+.

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:

Frequently Asked Questions

Why does mdformat backslash escape special syntax specific to MkDocs / Hugo / Obsidian / GitHub / some other Markdown engine?

Mdformat is a CommonMark formatter. It doesn't have out-of-the-box support for syntax other than what is defined in the CommonMark specification.

The custom syntax that these Markdown engines introduce typically redefines the meaning of angle brackets, square brackets, parentheses, hash character — characters that are special in CommonMark. Mdformat often resorts to backslash escaping these characters to ensure its formatting changes never alter a rendered document.

Additionally some engines, namely MkDocs, do not support CommonMark to begin with, so incompatibilities are unavoidable.

Luckily mdformat is extensible by plugins. For many Markdown engines you'll find support by searching the plugin docs or mdformat GitHub topic.

You may also want to consider a documentation generator that adheres to CommonMark as its base syntax e.g. mdBook or Sphinx with Markdown.

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 (v3.3.3) yet.

Prettier (v3.3.3), being able to format many languages other than Markdown, is a large package with 73 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 😄.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mdformat-0.7.22.tar.gz (34.6 kB view details)

Uploaded Source

Built Distribution

mdformat-0.7.22-py3-none-any.whl (34.4 kB view details)

Uploaded Python 3

File details

Details for the file mdformat-0.7.22.tar.gz.

File metadata

  • Download URL: mdformat-0.7.22.tar.gz
  • Upload date:
  • Size: 34.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.1

File hashes

Hashes for mdformat-0.7.22.tar.gz
Algorithm Hash digest
SHA256 eef84fa8f233d3162734683c2a8a6222227a229b9206872e6139658d99acb1ea
MD5 25622674399dbd56ff9b05704bf751d7
BLAKE2b-256 fcebb5cbf2484411af039a3d4aeb53a5160fae25dd8c84af6a4243bc2f3fedb3

See more details on using hashes here.

File details

Details for the file mdformat-0.7.22-py3-none-any.whl.

File metadata

  • Download URL: mdformat-0.7.22-py3-none-any.whl
  • Upload date:
  • Size: 34.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.1

File hashes

Hashes for mdformat-0.7.22-py3-none-any.whl
Algorithm Hash digest
SHA256 61122637c9e1d9be1329054f3fa216559f0d1f722b7919b060a8c2a4ae1850e5
MD5 fa342de020eddb870a275cd5203c7321
BLAKE2b-256 f26f94a7344f6d634fe3563bea8b33bccedee37f2726f7807e9a58440dc91627

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page