Repository navigation
Description
Hello, after rebuilding one of my Mkdocs sites that use Python-Markdown, I noticed some bold links broke (they worked OK before):
- __[:material-language-markdown-outline: Python Markdown](https://python-markdown.github.io/){:target="_blank"}__: processador de Markdown per a Python.
I asked a LLM to help me figure it out, and it pointed me here.
Below, I attach what the LLM figured out.
Summary
Since 3.11.1, __strong__ text is no longer rendered as strong when it contains a single underscore at the start of a word. Depending on the content, the delimiters are either left as literal text or rendered as nested <em> elements with a stray _.
A common way to hit this is a link with {target="_blank"} inside strong text, because emphasis is processed while the attribute list is still plain text.
The same text using ** still renders as strong.
Minimal reproduction
import markdown
print(markdown.markdown('__foo _bar__'))
print(markdown.markdown('__[A](u){target="_blank"}__: x', extensions=['attr_list']))Output on 3.11.2 and on master (0bfd8c3e):
<p>_<em>foo <em>bar</em></em></p>
<p>__<a href="u" target="_blank">A</a>__: x</p>Output on 3.10.3 and 3.11.0:
<p><strong>foo _bar</strong></p>
<p><strong><a href="u" target="_blank">A</a></strong>: x</p>Version comparison
Reproduced with Python 3.14. Only the attr_list cases have an extension enabled.
| Input | 3.10.3 | 3.11.0 | 3.11.1 | 3.11.2 | master |
|---|---|---|---|---|---|
__foo _bar__ |
Strong | Strong | Nested <em> |
Nested <em> |
Nested <em> |
__a _b__ c |
Strong | Strong | Nested <em> |
Nested <em> |
Nested <em> |
__a "_b" c__ d |
Strong | Strong | Nested <em> |
Nested <em> |
Nested <em> |
__[A](u){target="_blank"}__: x |
Strong | Strong | Literal __ |
Literal __ |
Literal __ |
**[A](u){target="_blank"}**: x |
Strong | Strong | Strong | Strong | Strong |
Expected behavior
I expected the output from 3.11.0 and earlier: the outer __ pair renders as <strong>, and the unmatched _ stays as literal text.
Context
The version comparison points to the emphasis rewrite in #1632, which first shipped in 3.11.1. I did not bisect to the individual commit.
#1630 is related, as it covers underscores in {target="_blank"} affecting italic text. A comment there notes that emphasis runs before attribute lists, so underscores sometimes need escaping. Escaping does work here ({target="\_blank"}), and so does moving the strong markers inside the link ([__A__](u){target="_blank"}).
However, the __foo _bar__ case involves no attribute list, and existing documents that rendered correctly through 3.11.0 change silently on upgrade. #1657 restored earlier behavior for a similar compatibility change, so I wanted to ask whether this one is intended.
I found this in a MkDocs-style documentation site, where a list of links in the form __[Name](url){:target="_blank"}__: description lost its bold formatting after a dependency update.
Activity
facelessuser commentedon Nov 5, 2026
I haven't gone through all of your cases yet, but the emphasis rewrite moved away from a series of regex patterns, that sometimes matches in inconsistent ways with poor performance at times. The new approach follows CommonMark behavior expect for their punctuation rules to preserve existing behavior in foreign text, which improved performance in many ways, and matches more consistently. Unfortunately, some small cases outside our test environment will change now that we have clear rules for emphasis token pairing, but those are impossible to keep with the new rules. We never tested for these cases nor do we guarantee these cases.
One think to note, with the way Python Markdown handles attributes, sometimes
_has always needed escaping. The emphasis rewrite does not guarantee attributes will not have to escape underscores, but may have moved when these non-ideal cases can occur. Punctuation rules, if we followed then, may have made this better in some cases, but would have regressed other expectations in Python Markdown.waylan commentedon Nov 5, 2026
In other words, you should be escaping all of your non-markup underscores. If you didn't need to before, that was a coincidence that we have never guaranteed to continue working.
My inclination is to close this, but I haven't inspected the report closely to see if there is any reported unintended behavior here.
facelessuser commentedon Nov 5, 2026
Everything matched CommonMark exactly except:
__[A](u){target="_blank"}__: x, and it is because we are missing the "rule of 3" from CommonMark. This wasn't captured in their suite of tests related to emphasis, but it is an easy fix. I'll create a PR.facelessuser commentedon Nov 5, 2026
I have a local fix and will provide a PR later today.
Apply the CommonMark rule of 3 which we missed.
joapuiib commentedon Nov 5, 2026
Thanks @facelessuser and @waylan for this quick resolution :)
Apply the CommonMark rule of 3 which we missed.
waylan commentedon Nov 5, 2026
I just released 3.11.3 which includes the fix for this.
joapuiib commentedon Nov 12, 2026
Thanks for the release! Unfortunately, the attribute list case still fails on 3.11.3; the output is actually different from 3.11.2:
<p>__<a href="u" target="_blank">A</a>__: x</p><p>__<a href="u">A</a>{target="<em>blank"}</em>_: x</p>master(a4d44288)<p><strong><a href="u" target="_blank">A</a></strong>: x</p>It renders correctly on current
master, so I guess 6f69248 ("Fix dropped text in emphasis handling") covers it and it will be solved in the next release.facelessuser commentedon Nov 12, 2026
The fix associated with this issue should have fixed it, and did fix it over in BetterEm (Python Markdown uses the same approach, without CommonMark punctuation rules), but I fumbled bringing over the changes, so two lines were missing.
6f69248 fixes the botched "rule of 3" fix and fixes the dropped text issues (which was a separate issue).
BetterEm uses the same logic and has all the fixes in the current release, but does add punctuation rules, but you can turn them off to have parity with Python Markdown core. As soon as the next Python Markdown is released, core will have the fix as well.