Metadata-Version: 2.4
Name: mdformat_mkdocs
Version: 5.2.0b2
Summary: An mdformat plugin for mkdocs and Material for MkDocs
Keywords: markdown,markdown-it,mdformat,mdformat_plugin_template
Author: kyleking
Author-email: kyleking <dev.act.kyle@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: mdformat>=0.7.19
Requires-Dist: mdformat-gfm>=0.3.6
Requires-Dist: mdit-py-plugins>=0.4.1
Requires-Dist: more-itertools>=10.5.0
Requires-Dist: mdformat-beautysh>=0.1.1 ; extra == 'recommended'
Requires-Dist: mdformat-config>=0.2.1 ; extra == 'recommended'
Requires-Dist: mdformat-footnote>=0.1.1 ; extra == 'recommended'
Requires-Dist: mdformat-front-matters>=0.1.0 ; extra == 'recommended'
Requires-Dist: mdformat-gfm>=1.0.0 ; extra == 'recommended'
Requires-Dist: mdformat-ruff>=0.1.3 ; extra == 'recommended'
Requires-Dist: mdformat-simple-breaks>=0.0.1 ; extra == 'recommended'
Requires-Dist: mdformat-web>=0.2.0 ; extra == 'recommended'
Requires-Dist: mdformat-wikilink>=0.2.0 ; extra == 'recommended'
Requires-Dist: setuptools ; extra == 'recommended'
Requires-Dist: mdformat-footnote>=0.1.0 ; extra == 'recommended-mdsf'
Requires-Dist: mdformat-front-matters>=1.0.1 ; extra == 'recommended-mdsf'
Requires-Dist: mdformat-gfm>=1.0.0 ; extra == 'recommended-mdsf'
Requires-Dist: mdformat-hooks>=0.1.0 ; extra == 'recommended-mdsf'
Requires-Dist: mdformat-simple-breaks>=0.0.1 ; extra == 'recommended-mdsf'
Requires-Dist: mdformat-wikilink>=0.2.0 ; extra == 'recommended-mdsf'
Requires-Dist: beartype>=0.21.0 ; extra == 'test'
Requires-Dist: hypothesis>=6.100.0 ; extra == 'test'
Requires-Dist: pytest>=9.0.1 ; extra == 'test'
Requires-Dist: pytest-beartype>=0.2.0 ; extra == 'test'
Requires-Dist: pytest-cov>=7.0.0 ; extra == 'test'
Requires-Dist: syrupy>=4.9.1 ; extra == 'test'
Requires-Python: >=3.10.0
Project-URL: Bug Tracker, https://github.com/kyleking/mdformat-mkdocs/issues
Project-URL: Changelog, https://github.com/kyleking/mdformat-mkdocs/releases
Project-URL: homepage, https://github.com/kyleking/mdformat-mkdocs
Provides-Extra: recommended
Provides-Extra: recommended-mdsf
Provides-Extra: test
Description-Content-Type: text/markdown

# mdformat-mkdocs

[![Build Status][ci-badge]][ci-link] [![PyPI version][pypi-badge]][pypi-link]

An [mdformat](https://github.com/executablebooks/mdformat) plugin for [mkdocs](https://github.com/mkdocs/mkdocs) and packages commonly used with MkDocs ([mkdocs-material](https://squidfunk.github.io/mkdocs-material), [mkdocstrings](https://mkdocstrings.github.io), and [python-markdown](https://python-markdown.github.io))

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`](https://github.com/executablebooks/mdformat?tab=readme-ov-file#options)
- [MkDocs-Material Admonitions\*](https://squidfunk.github.io/mkdocs-material/reference/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](https://github.com/KyleKing/mdformat-admon/pull/22))
- [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.
- [MkDocs-Material Definition Lists](https://squidfunk.github.io/mkdocs-material/reference/lists/#using-definition-lists)
- [mkdocstrings Injection Blocks](https://mkdocstrings.github.io/usage/)
    - Preserves `:::` identifier blocks and their indented YAML options verbatim
- [mkdocstrings Anchors (autorefs)](https://mkdocstrings.github.io/autorefs/#markdown-anchors)
- [mkdocstrings Cross-References](https://mkdocstrings.github.io/usage/#cross-references)
- [Python Markdown "Abbreviations"\*](https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-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 "Attribute Lists"](https://python-markdown.github.io/extensions/attr_list)
    - Preserves attribute list syntax when using `--wrap` mode
- [PyMdown Extensions "Arithmatex" (Math/LaTeX Support)](https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex) ([Material for MkDocs Math](https://squidfunk.github.io/mkdocs-material/reference/math))
    - This plugin combines three math rendering plugins from mdit-py-plugins:
        1. **dollarmath**: Handles `$...$` (inline) and `$$...$$` (block) with smart dollar mode that prevents false positives (e.g., `$3.00` is not treated as math)
        1. **texmath**: Handles `\(...\)` (inline) and `\[...\]` (block) LaTeX bracket notation
        1. **amsmath**: Handles LaTeX environments like `\begin{align}...\end{align}`, `\begin{cases}...\end{cases}`, `\begin{matrix}...\end{matrix}`, etc.
    - Can be deactivated entirely with the `--no-mkdocs-math` flag
- [Python Markdown "Snippets"\*](https://facelessuser.github.io/pymdown-extensions/extensions/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

### Features with Implicit Support

The following MkDocs/Material/PyMdown syntax passes through mdformat-mkdocs unchanged — it is not modified or corrupted, but it is also not actively normalized:

- [PyMdown Keys](https://facelessuser.github.io/pymdown-extensions/extensions/keys/) — `++ctrl+alt+del++` (not a markdown construct, preserved as-is)
- [PyMdown Critic Markup](https://facelessuser.github.io/pymdown-extensions/extensions/critic/) — `{--deleted--}`, `{++added++}`, `{~~old~>new~~}`, `{==highlight==}`, `{>>comment<<}`
- [PyMdown Highlight](https://facelessuser.github.io/pymdown-extensions/extensions/mark/) — `==marked text==`
- [PyMdown Caret / Tilde](https://facelessuser.github.io/pymdown-extensions/extensions/caret/) — `H^2^O`, `CH~3~OH`
- [PyMdown Emoji](https://facelessuser.github.io/pymdown-extensions/extensions/emoji/) — `:smile:`, `:material-icon:`
- [PyMdown InlineHilite](https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/) — language hints inside backtick spans (`:::python code`) are never modified
- [PyMdown SmartSymbols](https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/) — `(c)`, `(tm)`, `--`, `-->` are plain ASCII in source and not touched
- [PyMdown MagicLink](https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/) — `@username`, `#123` are plain text and pass through
- [Material Grids](https://squidfunk.github.io/mkdocs-material/reference/grids/) — `<div class="grid cards" markdown>` is an HTML block; content is preserved but markdown inside is not reformatted
- [Mermaid / Superfences](https://squidfunk.github.io/mkdocs-material/reference/diagrams/) — diagram code inside fenced blocks is never modified

**Note on [PyMdown ProgressBar](https://facelessuser.github.io/pymdown-extensions/extensions/progressbar/)**: The syntax `[=50% "50%"]` resembles an undefined link reference and will be escaped to `\[=50% "50%"\]` by default. Use `--ignore-missing-references` to preserve it, or avoid this extension if you use mdformat without that flag.

See the example test files, [./tests/pre-commit-test.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/tests/pre-commit-test.md) and [./tests/format/fixtures.md](https://raw.githubusercontent.com/KyleKing/mdformat-mkdocs/main/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](https://mdformat.readthedocs.io/en/stable/users/plugins.html)

### Optional Extras

This package specifies two optional "extra" plugins (`'recommended'` and `'recommended-mdsf'` ) for plugins that work well with typical documentation managed by `mkdocs`:

- For `'recommended'`:
    - [mdformat-beautysh](https://pypi.org/project/mdformat-beautysh)
    - [mdformat-config](https://pypi.org/project/mdformat-config)
    - [mdformat-footnote](https://pypi.org/project/mdformat-footnote)
    - [mdformat-front-matters](https://pypi.org/project/mdformat-front-matters) (previously [mdformat-frontmatter](https://pypi.org/project/mdformat-frontmatter))
    - [mdformat-gfm](https://github.com/hukkin/mdformat-gfm)
    - [mdformat-ruff](https://github.com/Freed-Wu/mdformat-ruff)
    - [mdformat-simple-breaks](https://pypi.org/project/mdformat-simple-breaks)
    - [mdformat-web](https://pypi.org/project/mdformat-web)
    - [mdformat-wikilink](https://github.com/tmr232/mdformat-wikilink)
- For `'recommended-mdsf'`:
    - Instead of `mdformat-beautysh`, `mdformat-config`, `mdformat-ruff`, and `mdformat-web`, the "mdsf" extras install `mdformat-hooks`, which allows the use of `mdsf` for formatting code blocks in hundreds of languages using CLI formatters you already have installed; however, this requires extra configuration, so make sure to see the README: <https://github.com/KyleKing/mdformat-hooks>

### pre-commit/prek

```yaml
repos:
  - repo: https://github.com/executablebooks/mdformat
    rev: 1.0.0
    hooks:
      - id: mdformat
        additional_dependencies:
          - mdformat-mkdocs
          # Or
          # - "mdformat-mkdocs[recommended-mdsf]>=5.1.0"
          # Or
          # - "mdformat-mkdocs[recommended]"
```

### uvx

```sh
uvx --with=mdformat-mkdocs mdformat
```

Or with pipx:

```sh
pipx install mdformat
pipx inject mdformat mdformat-mkdocs
```

## 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>

```py
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.

    ```txt
    # 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

- `--no-mkdocs-math` if set, deactivate math/LaTeX rendering (Arithmatex). By default, math is enabled. This can be useful if you want to format markdown without processing math syntax.

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

```toml
# .mdformat.toml

[plugin.mkdocs]
align_semantic_breaks_in_lists = true
ignore_missing_references = true
no_mkdocs_math = true
```

## Contributing

See [CONTRIBUTING.md](https://github.com/kyleking/mdformat-mkdocs/blob/main/CONTRIBUTING.md)

[ci-badge]: https://github.com/kyleking/mdformat-mkdocs/actions/workflows/tests.yml/badge.svg?branch=main
[ci-link]: https://github.com/kyleking/mdformat-mkdocs/actions?query=workflow%3ACI+branch%3Amain+event%3Apush
[pypi-badge]: https://img.shields.io/pypi/v/mdformat-mkdocs.svg
[pypi-link]: https://pypi.org/project/mdformat-mkdocs
