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 (see https://github.com/topics/mdformat for more!)¶
| Plugin | 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 or Docker installation |
| mdformat-web | javascript, js, css, html, xml |
Parser extension plugins¶
Markdown-it-py offers a range of useful extensions to the base CommonMark parser (see the documented list).
Mdformat features a plugin system to support the loading and rendering of such extensions.
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 (see https://github.com/topics/mdformat for more!)¶
| Plugin | Syntax Extensions | 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¶
Other plugins that don’t fit the above categories.
Existing plugins¶
| Plugin | Description |
|---|---|
| mdformat-pyproject | Adds support for loading options from a [tool.mdformat] section inside the pyproject.toml file, if it exists |
| mdformat-simple-breaks | Render thematic breaks using three dashes instead of 70 underscores |