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*
  • *Note: mdformat-admon will format the same admonitions, but for consistency with the mkdocs styleguide, an extra space will be added by this package (#22)
• 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
• Python Markdown "Snippets"*
  • *Note: the markup (HTML) renders the plain text without implementing the snippet logic. I'm open to contributions if anyone needs full support for snippets

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.19
    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>

Configuration

mdformat-mkdocs adds the CLI arguments:

• --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. "mdformat --align-semantic-breaks-in-lists"
  1. Semantic line feed where the following line is
     three spaces deep

• --ignore-missing-references if set, do not escape link references when no definition is found. This is required when references are dynamic, such as with python mkdocstrings

You can also use the toml configuration (https://mdformat.readthedocs.io/en/stable/users/configuration_file.html):

# .mdformat.toml

[plugin.mkdocs]
align_semantic_breaks_in_lists = true
ignore_missing_references = true

Contributing

See CONTRIBUTING.md