Skip to content

fix: resolve reference links when label contains code spans (fixes #495)#1609

Open
gaoflow wants to merge 1 commit into
Python-Markdown:masterfrom
gaoflow:fix/reference-link-backtick
Open

fix: resolve reference links when label contains code spans (fixes #495)#1609
gaoflow wants to merge 1 commit into
Python-Markdown:masterfrom
gaoflow:fix/reference-link-backtick

Conversation

@gaoflow

@gaoflow gaoflow commented Jun 24, 2026

Copy link
Copy Markdown

Reference links whose label contains backtick code spans
([text with \code`][]) fail to resolve even when the matching reference definition exists. The raw bracket syntax appears in the output instead of a resolved ` tag.

Fixes #495 (open since 2016).

Before:

[formatting contains `code` backticks][]
[formatting contains `code` backticks]: https://example.com/ref
→ <p>[formatting contains <code>code</code> backticks][]</p>

After:

<p><a href="https://example.com/ref">formatting contains
  <code>code</code> backticks</a></p>

Root cause: Inline processing runs in priority order. The backtick
processor (priority 190) replaces code spans with opaque placeholders
before the reference processor (priority 170) attempts lookup. The
stored reference definition key contains literal backtick text,
creating a mismatch against the placeholder-containing ID.

Fix (+38 lines in 2 files):

  1. inlinepatterns.py_unescapeId() method resolves inline
    placeholders back to plain text before reference lookup, using
    itertext() to strip markup from stashed elements.
  2. blockprocessors.pyReferenceProcessor.run() also stores
    each definition under a backtick-stripped key for normalization.

The sibling inline-link form [text with \code`](url)` works
correctly — this fix brings reference links to parity.

761/761 tests pass (0 regressions).

This pull request was prepared with the assistance of AI, under my
direction and review.

When a reference link label (or text in the [text][] shortcut form)
contains backtick code spans, the inline backtick processor (priority
190) replaces them with placeholders before the reference processor
(priority 170) resolves the link. The stored reference definition key
contains the raw backtick text, causing a lookup mismatch.

Fix this by:
1. Adding _unescapeId() to resolve inline placeholders in the reference
   ID back to plain text before lookup.
2. Storing reference definitions under a backtick-stripped key so that
   code spans with varying backtick counts all normalize to the same key.

Fixes the long-standing issue where [label with `code`][] would not
resolve even when [label with `code`]: url was defined.
@waylan

waylan commented Jun 24, 2026

Copy link
Copy Markdown
Member

Thank you for your submission. A few things to note.

First of all, this does not include any tests to verify that it works as expected.

Second, thank you for noting that AI assisted. However, it is not clear if you mean that AI wrote the code and you reviewed it or that AI assisted in finding where the error occurred and you wrote the code. This hasn't really come up yet, so we don't have a clear policy, but my inclination is to only accept human-written code.

@waylan waylan added more-info-needed More information needs to be provided. requires-changes Awaiting updates after a review. labels Jun 24, 2026
@waylan

waylan commented Jun 24, 2026

Copy link
Copy Markdown
Member

With a cursory look at the code, it appears that it is simply removing backticks from reference link labels. While that may seem to work in simple cases, it is not a viable solution. Consider this example:

[link with `code`] and [link with code]

[link with `code`] https://example.com
[link with code] https://notexample.com

If I understand the code correctly; both reference links would resolve to https://example.com which would be wrong.

The correct solution is to just require the document author to use better references. For example:

[link with `code`][1] and [link with code][2]

[1] https://example.com
[2] https://notexample.com

And that works without any changes to the code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

more-info-needed More information needs to be provided. requires-changes Awaiting updates after a review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Reference links don't work if the link label contains backticks

2 participants