Repository navigation
Re-evaluate Usage of mdformat (Enable and Disable via Comments) #103
Description
Currently mdformat will automatically re-format markdown used by mkdocstrings, as well as mkdocs admonitions, in a way that breaks their functionality.
Example desired mkdocstrings markdown:
::: smart_control.dataset.dataset.BuildingDataset
options:
members_order: source
group_by_category: false
Example desired mkdocs admonition markdown:
!!! info "Important: Installing Pre-commit Hooks"
To enable the pre-commit hooks, you must perform a one-time setup by running
`pre-commit install`. This will create or update ".git/hooks/pre-commit".
Currently there is no way of disabling mdformat on a line-by-line basis. So we are currently a) ignoring the mkdocstrings related files from being formatted by mdformat, and b) not using admonitions.
See:
However if mdformat implemented comments to enable and disable specific lines, that would solve both of these issues.
Without the ability to enable and disable specific lines from being formatted, if we want to solve these issues we will have to discontinue use of mdformat in favor of another tool.
We might want to investigate a different tool for markdown formatting (revisiting #58).
Activity
[-]Re-evaluate usage of `mdformat` (Enable and Disable `mdformat` via Comments)[/-][+]Re-evaluate Usage of `mdformat` (Enable and Disable via Comments)[/+]pawamoy commentedon Jul 11, 2025
I'm tracking mdformat incompatibilities with mkdocs/mkdocstrings/other here: pawamoy/copier-uv#46 (comment), you might find some useful info 🙂
s2t2 commentedon Jul 14, 2025
We can consider trying
mdformat-mkdocs, which seems like it might better handle the normal mkdocs use cases:https://github.com/KyleKing/mdformat-mkdocs
KyleKing commentedon Jul 15, 2025
I’m the author of “mdformat-mkdocs” and would be happy to receive feedback if you run into any issues. I’ve been busier the past year, but I’m still monitoring for bug reports
The mkdocstrings format could be supported with a plugin, but I’m not aware of one off the top of my head
s2t2 commentedon Aug 20, 2026
@KyleKing it looks like we will be able to use "mdformat-mkdocs" (see #176)
Preserve MkDocs syntax during Markdown formatting (google#176)