An mdformat plugin for mkdocs and packages commonly used with MkDocs (mkdocs-material, mkdocstrings, and python-markdown)
Supports:
--align-semantic-breaks-in-lists
, the nested indent for ordered lists is three, but is otherwise a multiple of four-
) instead of *
1.
or 0.
) unless --number
is specified, then mdformat-mkdocs
will apply consecutive numbering to ordered lists for consistency with mdformat
See the example test files, ./tests/pre-commit-test.md and ./tests/format/fixtures.md
mdformat
UsageAdd this package wherever you use mdformat
and the plugin will be auto-recognized. No additional configuration necessary. For additional information on plugins, see the official mdformat
documentation here
Tip: this package specifies an "extra" ('recommended'
) for plugins that work well with typical documentation managed by mkdocs
:
repos:
- repo: https://github.com/executablebooks/mdformat
rev: 0.7.16
hooks:
- id: mdformat
additional_dependencies:
- mdformat-mkdocs>=2.1.0
# Or
# - "mdformat-mkdocs[recommended]>=2.1.0"
pipx install mdformat
pipx inject mdformat mdformat-mkdocs
# Or
# pipx inject mdformat "mdformat-mkdocs[recommended]"
To generate HTML output, material_admon_plugin
can be imported from mdit_plugins
. More plugins will be added in the future. For more guidance on MarkdownIt
, see the docs: https://markdown-it-py.readthedocs.io/en/latest/using.html#the-parser
from markdown_it import MarkdownIt
from mdformat_mkdocs.mdit_plugins import material_admon_plugin
md = MarkdownIt()
md.use(material_admon_plugin)
text = "??? note\n content"
md.render(text)
# <details class="note">
# <summary>Note</summary>
# <p>content</p>
# </details>
mdformat-mkdocs
adds the CLI argument --align-semantic-breaks-in-lists
to optionally align line breaks in numbered lists to 3-spaces. If not specified, the default of 4-indents is followed universally.
# with: mdformat
1. Semantic line feed where the following line is
three spaces deep
# vs. with: mdformat --align-semantic-breaks-in-lists
1. Semantic line feed where the following line is
three spaces deep
Note: the align-semantic-breaks-in-lists
setting is not supported in the configuration file yet (https://github.com/executablebooks/mdformat/issues/378)
See CONTRIBUTING.md