mdformat icon indicating copy to clipboard operation
mdformat copied to clipboard

Don't escape literal underscores

Open fyliu opened this issue 3 months ago • 1 comments

Describe the bug

context

When I run mdformat on this text: When using *target=_blank* also adding *rel="noopener"* to the tag ensures that new page runs in a separate process.

expectation

I expected it to leave it alone as it is correct.

bug

But instead, it escaped the literal underscore _, like this: When using *target=\_blank* also adding *rel="noopener"* to the tag ensures that new page runs in a separate process.

  • I know it renders the same in HTML, but it's an unnecessary character in the markdown.

another example

-Please write a user story for this feature suggestion in the following format: As a ______, I want to do X for Y reason and replace this text with it.
+Please write a user story for this feature suggestion in the following format: As a \_\_\_\_\_\_, I want to do X for Y reason and replace this text with it.

Discussion

  • I believe it's the wrong, or at least unnecessary, behavior to escape the literal underscores in my examples.

    By CommonMark standard, rule 9 from the CommonMark specs Section 6.2 Emphasis and Strong Emphasis, the underscores in these examples are not qualified emphasis delimiters, so they should be considered literals.

  • I raised an issue at mdformat-mkdocs and the maintainer pointed me to here as the better place to solve this.

Reproduce the bug

❯ echo "When using *target=_blank* also adding *rel=\"noopener\"* to the tag ensures that new page runs in a separate process." | uv run mdformat - 
When using *target=\_blank* also adding *rel="noopener"* to the tag ensures that new page runs in a separate process.

List your environment

❯ mdformat --version
mdformat 1.0.0

fyliu avatar Oct 20 '25 04:10 fyliu

Any progress on this?

alam-shahul avatar Nov 25 '25 18:11 alam-shahul