mdformat-mkdocs 2.0.0rc2

An mdformat plugin for mkdocs.

mdformat-mkdocs

---

"v2.0.0rc#" Warning

To avoid unexpected formatting errors, you must install mdformat-gfm separately until this issue is resolved: https://github.com/hukkin/mdformat-gfm/issues/31

For pre-commit, this would be something like:

repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 0.7.17
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-mkdocs[recommended]>=2.0.0rc2
          - mdformat-gfm@git+https://github.com/hukkin/mdformat-gfm.git

For any other usage with pip, you will need some variation of:

pip install mdformat-gfm@git+https://github.com/hukkin/mdformat-gfm.git

---

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-toc
• mdformat-web

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.0"

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