mdformat fails with “renders to different HTML” when inline code span contains trailing whitespace

[tr0k]

mdformat fails with:

Formatted Markdown renders to different HTML than input Markdown.

when an inline code span contains trailing whitespace inside the backticks.

This makes formatting impossible for otherwise valid Markdown.

This appears to be triggered only when the mdformat-mkdocs plugin is enabled.

Environment

mdformat==1.0.0
mdformat-mkdocs==5.1.4
markdown-it-py==4.0.0
mdit-py-plugins==0.5.0
pre-commit
python 3.13 (also reproducible after clean environment rebuild)
macOS

Minimal reproduction

test.md

- example `test `

Run:

pre-commit run mdformat --files test.md -v

Actual behavior

Error: Could not format
Formatted Markdown renders to different HTML than input Markdown.

Expected behavior

Formatting should succeed (or at least not fail hard).
Trailing whitespace inside inline code spans should not cause HTML instability.

Observations

Works:

`test`
`test test`

Fails:

`test `

Removing only the trailing space fixes it.

This suggests the plugin/parser combination produces different HTML before vs after formatting when trailing whitespace exists inside inline code.

Notes

Reproduces consistently after:

pre-commit clean

So it’s not cache-related.

[KyleKing]

Hi @tr0k, thanks for using mdformat-mkdocs!

For this issue, do you expect the trailing space to be preserved? If so, the trailing space removal is intentional to support expected formatting and trim extra space (not usually intentional), so I would need to understand more about your use case.

If not, you can do a one time run of mdformat --no-validate and check the results in version control. I can't think of a workaround that would mdformat-mkdocs to reformat without modifying the HTML and failing the validation or using the unsafe flag to turn off all validation for the plugin.

I would like more context and may be able to help figure out a good solution!

[tr0k]

Hi @KyleKing,

Thanks for the prompt reply.

I don't need the trailing space to be preserved.

The problem is not formatting semantics - it's that mdformat hard-fails with:

Formatted Markdown renders to different HTML than input Markdown

So the formatter refuses to run at all, which blocks pre-commit and CI.

From a user perspective:

• Input Markdown with `test ` is valid
• Formatter should either:
  • safely normalize it to `test` and continue, or
  • warn
• but not abort formatting entirely

Currently a single trailing space inside an inline code span makes the whole file unformattable.
Minimal repro:

- example `test `

mdformat fails

- example `test`

works

So this looks like a validation mismatch between pre/post HTML rendering rather than intentional trimming behavior.

If trimming is intentional, the validation step probably shouldn't treat this as an HTML change error. Also, I didn't see this problem in the previous version before I did pre-commit clean.

Let me know if you'd prefer a smaller repro or different environment details.

[KyleKing]

I see. Sorry, It's been a busy month, so I'm just catching up. I pushed a probable fix in v5.1.5b, if you have a chance to try it out. I'll try to make a full release in the next week or two with the other open issues

[KyleKing]

I'll try to get a full release out soon, but I'm wrapping up new pre-release canary testing on real use cases

If you have a chance to try the beta, let me know if you run into any issues. I've released 5.2.0b1 (https://pypi.org/project/mdformat-mkdocs/5.2.0b1) with some additional fixes

[fannedalk]

I also experience the same issue, even with the latest beta