# 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](../contributors/contributing.md) 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`](https://github.com/hukkin/mdformat-black) plugin is installed in the environment, mdformat CLI will automatically format Python code blocks with [Black](https://github.com/psf/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: ````python 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](https://github.com/topics/mdformat) 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](https://spec.commonmark.org/current/). 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: ```python 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](https://github.com/topics/mdformat) 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](https://github.com/topics/mdformat) 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