Formatting Issues with mdformat-mkdocs

[arv-anshul]

First of all, thank you for this amazing formatter. 🙏

I learned about mdformat-mkdocs from the @astral-sh/ruff repository.

When I tried using mdformat-mkdocs on my repository, I encountered some formatting issues that seem to stem from how the plugin handles specific mkdocs scenarios. I’m opening this issue to highlight these problems. If I’ve made any mistakes in my usage, please feel free to correct me.

⚙️ Configuration Used to Format My Repo

Initially, I used the formatter directly with pre-commit, as recommended. However, this formats all files in one go, making it difficult to identify specific issues.

To test individual files, I installed mdformat and mdformat-mkdocs using uvx:

uvx --from mdformat --with "mdformat-mkdocs[recommended]" mdformat docs/index.md

.mdformat.toml

wrap = 120
number = true
end_of_line = "lf"
validate = true

# The following doesn't work with the mdformat CLI.
# I have to explicitly specify the `--align-semantic-breaks-in-lists` flag.
[plugin.mkdocs]
align_semantic_breaks_in_lists = true
ignore_missing_references = false

As the [plugin.mkdocs] does work from .mdformat.toml so I have used this command to make it into effect.

uvx --from mdformat --with "mdformat-mkdocs[recommended]" mdformat --align-semantic-breaks-in-lists docs/index.md

---

Bug: Configuration Not Recognized

The configurations specified under the [plugin.mkdocs] section in .mdformat.toml are not recognized by the mdformat CLI. Other configurations work as expected. Please investigate and resolve this inconsistency.

---

Scenarios to Address

• Attribute Lists: Using --wrap causes mdformat to split {:.class1 .class2} into a new line if it exceeds the wrapping limit. This breaks rendering since the attribute list is no longer correctly applied.
• Jinja Templates: The same issue as above occurs with Jinja templates. While I’ve observed other formatting problems with Jinja, I will report them separately if they are within the scope of this plugin.
•   Replacement: The formatter replaces   with a Unicode character. Is there a way to disable this behavior?
• LaTeX Expressions: Pages containing LaTeX expressions often cause the formatter to throw the following error:

  Error: Could not format
  "path/to/page-containing-latex-expr.md".
  
  Formatted Markdown renders to different HTML than input Markdown. This is a bug
  in mdformat or one of its installed plugins. Please retry without any plugins
  installed. If this error persists, report an issue including the input Markdown
  on https://github.com/hukkin/mdformat/issues. If not, report an issue on the
  malfunctioning plugin's issue tracker.
  

  I understand that using --no-validate bypasses this issue, but a proper fix would be appreciated.

[KyleKing]

Thank you for submitting such a detailed issue and you have a nice blog! I'll try to review and release fixes when I have time over the next few weeks

[KyleKing]

Attribute Lists: Using --wrap causes mdformat to split {:.class1 .class2} into a new line if it exceeds the wrapping limit. This breaks rendering since the attribute list is no longer correctly applied.

The wrap logic in mdformat is challenging to workaround. For the 4-space indents this package provides, I have to insert a character that is unlikely to appear normally, allow mdformat to wrap, then replace that character. The same strategy would be necessary to prevent these sections from being split across lines and would be difficult to implement and maintain.

mdformat-mkdocs/mdformat_mkdocs/_postprocess_inline.py

Lines 9 to 10 in 1a744f6

	FILLER = FILLER_CHAR * (MKDOCS_INDENT_COUNT - 2) # `mdformat` default is two spaces
	"""A spacer that is inserted and then removed to ensure proper word wrap."""

Jinja Templates: The same issue as above occurs with Jinja templates. While I’ve observed other formatting problems with Jinja, I will report them separately if they are within the scope of this plugin.

Formatting Jinja is challenging and outside of the scope of this plugin. A standalone mdformat-jinja plugin could tokenize the Jinja-specific syntax and be composable with other plugins. However, if you are using Jinja for HTML templates, you could use https://www.djlint.com/docs/formatter today

  Replacement: The formatter replaces   with a Unicode character. Is there a way to disable this behavior?

There is an existing issue reported on mdformat (hukkin/mdformat#261) and still the default behavior today. I would recommend using CSS padding/margin instead

https://github.com/hukkin/mdformat/blob/f6ce9c95a374b7aafd15cab080a2c7a8db435984/src/mdformat/renderer/_context.py#L138-L140

[KyleKing]

The alternative syntax using backticks appears to work with mdformat today and would be my recommendation: #48 (comment)

In the future, someone could build a plugin that will format the LaTeX directly similar to how mdformat-ruff and other code formatters work (https://mdformat.readthedocs.io/en/stable/contributors/contributing.html#developing-code-formatter-plugins) rather than supporting the arbitrary Arithmatex format

[KyleKing]

I've fixed the issues with .mdformat.toml in the latest release (4.1.2) and submitted a feature request upstream to add a warning: hukkin/mdformat#507

[arv-anshul]

The wrap logic for Attribute Lists...

🤔 Can't you do something to prevent the wrapping for Attribute Lists as formatter do for link syntax [link](url) or image syntax ![alt](image-url). Just break/move it to next line.

[KyleKing]

The wrap logic for Attribute Lists...

🤔 Can't you do something to prevent the wrapping for Attribute Lists as formatter do for link syntax [link](url) or image syntax ![alt](image-url). Just break/move it to next line.

Good point. I thought URLs worked because they lack internal whitespace, but the alt-text variation is preserved. Testing See [https://mdformat.readthedocs.io/en/stable/contributors/contributing.html#developing-code-formatter-plugins](https://mdformat.readthedocs.io/en/stable/contributors/contributing.html#developing-code-formatter-plugins "Code Formatter Plugin Link") for more. with --wrap=80 keeps the URL, but splits the rest of the paragraph text across three lines

I'm working on a fix to recognize attribute lists now, which should probably be done by early next week when I find time

[bittorala]

Hello!

First of all thank you to both of you for the tool and the exhaustive description of possible enhancements.

Could something be done about TeX equations?

As things stand, this Markdown

$$
ReLU(x) =
     \begin{cases}
       x &\quad\text{if } x > 0\\\
       0 &\quad\text{otherwise}
     \end{cases}
$$

\[ x = \frac{4}{5} \]

What about inline expressions? $\Delta_{distance}= \text{Speed} \cdot \text{Time}$

gets formatted as

$$
ReLU(x) =
\\begin{cases}
x &\\quad\\text{if } x > 0\\\
0 &\\quad\\text{otherwise}
\\end{cases}
$$

[ x = \\frac{4}{5} ]

What about inline expressions? $\\Delta\_{distance}= \\text{Speed} \\cdot \\text{Time}$

which is not valid TeX anymore:

Issues:

• Single backslashes and underscores have been escaped.
• The backslashes in in the \[ delimiters are simply removed.

What do you reckon? Maybe this should be adressed in a dedicated plugin (to be fair it is quite a distinct feature that applies outside mkdocs too), or do you plan on adding it to mdformat-mkdocs?

[KyleKing]

Sorry for the delay! I'll take a look this week