An mdformat plugin for mkdocs.
Project description
mdformat-mkdocs
An mdformat plugin for mkdocs and mkdocs-material in particular.
Supports:
- Indents are converted to 4-spaces instead of 2
- Note: see caveats when using the optional Semantic Indents on numbered lists which may not be a full multiple of 4
- List bullets are converted to dashes instead of
*
- Admonitions (extends
mdformat-admon
) - MKDocs-Material Content Tabs (https://squidfunk.github.io/mkdocs-material/reference/content-tabs)
- Note: the markup (HTML) rendered by this plugin is sufficient for formatting but not for viewing in a browser. Please open an issue if you have a need to generate valid HTML.
See the example test files, ./tests/pre-commit-test.md and ./tests/format/fixtures.md
mdformat
Usage
Add 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 mkdocs
:
- mdformat-beautysh
- mdformat-black
- mdformat-config
- mdformat-footnote
- mdformat-frontmatter
- mdformat-simple-breaks
- mdformat-tables
- mdformat-web
- mdformat-wikilink
Pre-Commit
repos:
- repo: https://github.com/executablebooks/mdformat
rev: 0.7.16
hooks:
- id: mdformat
additional_dependencies:
- mdformat-mkdocs>=2.0.0
# Or
# - "mdformat-mkdocs[recommended]>=2.0.6"
pipx
pipx install mdformat
pipx inject mdformat mdformat-mkdocs
# Or
# pipx inject mdformat "mdformat-mkdocs[recommended]"
HTML Rendering
To generate HTML output, mkdocs_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 mkdocs_admon_plugin
md = MarkdownIt()
md.use(mkdocs_admon_plugin)
text = "??? note\n content"
md.render(text)
# <details class="note">
# <summary>Note</summary>
# <p>content</p>
# </details>
CLI Options
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)
Contributing
See CONTRIBUTING.md
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mdformat_mkdocs-2.0.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fb0f84e3412f4f2a955967aa3933f17e4f76e9a051ffe92a9493de5bfa21f6ef |
|
MD5 | ae985ae8600d0d2e1659b66bdc9e559b |
|
BLAKE2b-256 | e7e2ed9ef5ed5ec83ca6adec7813b1a0e207b85b730113c240f84187a23b5200 |