mdformat-mkdocs

An mdformat plugin for mkdocs and packages commonly used with MkDocs (mkdocs-material, mkdocstrings, and python-markdown)

Supports:

• Indents are converted to four-spaces instead of two
  • Note: when specifying --align-semantic-breaks-in-lists, the nested indent for ordered lists is three, but is otherwise a multiple of four
• Unordered list bullets are converted to dashes (-) instead of *
• By default, ordered lists are standardized on a single digit (1. or 0.) unless --number is specified, then mdformat-mkdocs will apply consecutive numbering to ordered lists for consistency with mdformat
• MkDocs-Material Admonitions
• MkDocs-Material 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.
• mkdocstrings Anchors (autorefs)
• mkdocstrings Cross-References
• Python Markdown "Abbreviations"*
  • *Note: the markup (HTML) rendered for abbreviations is not useful for rendering. If important, I'm open to contributions because the implementation could be challenging

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 typical documentation managed by 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.18
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-mkdocs
          # Or
          # - "mdformat-mkdocs[recommended]"

pipx/uv

pipx install mdformat
pipx inject mdformat mdformat-mkdocs

Or with uv:

uv tool run --from mdformat-mkdocs mdformat

HTML Rendering

To generate HTML output, any of the plugins can be imported from mdit_plugins. 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,
    material_content_tabs_plugin,
    mkdocstrings_autorefs_plugin,
    mkdocstrings_crossreference_plugin,
    pymd_abbreviations_plugin,
)

md = MarkdownIt()
md.use(material_admon_plugin)
md.use(material_content_tabs_plugin)
md.use(mkdocstrings_autorefs_plugin)
md.use(mkdocstrings_crossreference_plugin)
md.use(pymd_abbreviations_plugin)

text = "- Line 1\n    - `bash command`\n    - Line 3"
md.render(text)
# <ul>
# <li>Line 1
# <ul>
# <li><code>bash command</code></li>
# <li>Line 3</li>
# </ul>
# </li>
# </ul>

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 (executablebooks/mdformat#378)

Contributing

See CONTRIBUTING.md