Plugins¶
Mdformat offers an extensible plugin system for code fence content formatting, Markdown parser extensions (like GFM tables), and modifying/adding other functionality. This document explains how to use plugins. If you want to create a new plugin, refer to the contributing docs.
Code formatter plugins¶
Mdformat features a plugin system to support formatting of Markdown code blocks where the coding language has been labeled.
For instance, if mdformat-black
plugin is installed in the environment,
mdformat CLI will automatically format Python code blocks with Black.
For stability, mdformat Python API behavior will not change simply due to a plugin being installed. Code formatters will have to be explicitly enabled in addition to being installed:
import mdformat
unformatted = "```python\n'''black converts quotes'''\n```\n"
# Pass in `codeformatters` here! It is an iterable of coding languages
# that should be formatted
formatted = mdformat.text(unformatted, codeformatters={"python"})
assert formatted == '```python\n"""black converts quotes"""\n```\n'
Existing plugins¶
This is a curated list of popular code formatter plugins. The list is not exhaustive. Explore mdformat’s GitHub topic for more.
Distribution | Supported languages | Notes |
---|---|---|
mdformat-beautysh | bash , sh |
|
mdformat-black | python |
|
mdformat-config | json , toml , yaml |
|
mdformat-gofmt | go |
Requires Go installation |
mdformat-ruff | python |
|
mdformat-rustfmt | rust |
Requires rustfmt installation |
mdformat-shfmt | bash , sh |
Requires either shfmt, Docker or Podman installation |
mdformat-web | javascript , js , css , html , xml |
Parser extension plugins¶
By default, mdformat only parses and renders CommonMark. Installed plugins can add extensions to the syntax, such as footnotes, tables, and other document elements.
For stability, mdformat Python API behavior will not change simply due to a plugin being installed. Extensions will have to be explicitly enabled in addition to being installed:
import mdformat
unformatted = "content...\n"
# Pass in `extensions` here! It is an iterable of extensions that should be loaded
formatted = mdformat.text(unformatted, extensions={"tables"})
Existing plugins¶
This is a curated list of popular parser extension plugins. The list is not exhaustive. Explore mdformat’s GitHub topic for more.
Distribution | Plugins | Description |
---|---|---|
mdformat-admon | admonition |
Adds support for python-markdown admonitions |
mdformat-deflist | deflist |
Adds support for Pandoc-style definition lists |
mdformat-footnote | footnote |
Adds support for Pandoc-style footnotes |
mdformat-frontmatter | frontmatter |
Adds support for front matter, and formats YAML front matter |
mdformat-gfm | gfm |
Changes target specification to GitHub Flavored Markdown (GFM) |
mdformat-gfm-alerts | gfm_alerts |
Extends GitHub Flavored Markdown (GFM) with "Alerts" |
mdformat-mkdocs | mkdocs |
Changes target specification to MKDocs. Indents lists with 4-spaces instead of 2 |
mdformat-myst | myst |
Changes target specification to MyST |
mdformat-tables | tables |
Adds support for GitHub Flavored Markdown style tables |
mdformat-toc | toc |
Adds the capability to auto-generate a table of contents |
Other misc plugins¶
Existing plugins¶
This is a curated list of other plugins that don’t fit the above categories. The list is not exhaustive. Explore mdformat’s GitHub topic for more.
Distribution | Plugins | Description |
---|---|---|
mdformat-pyproject | pyproject |
Adds support for loading options from a [tool.mdformat] section inside the pyproject.toml file, if it exists |
mdformat-simple-breaks | simple_breaks |
Render thematic breaks using three dashes instead of 70 underscores |