🐛 FIX: Correctly encode "&" in Markdown URLs by not HTML-escaping refuri

`escapeHtml` was called on the URL before storing it in the `refuri`
attribute of a reference node, converting `&` to `&`. This caused
double-escaping when Sphinx's HTML writer later escaped the `&` in
`&` to produce `&` in the final `href` attribute, breaking
URLs with query parameters.

The `refuri` attribute should hold the raw URL; HTML-escaping is the
responsibility of the output writer. The other characters `escapeHtml`
converts (`<`, `>`, `"`) are already percent-encoded by `normalizeLink`
before reaching this point, so removing the call has no other effect.

Author: mb

myst_parser/mdit_to_docutils/base.py

@@ -31,7 +31,6 @@
 from docutils.utils import Reporter, SystemMessage, new_document
 from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines
 from markdown_it import MarkdownIt
-from markdown_it.common.utils import escapeHtml
 from markdown_it.renderer import RendererProtocol
 from markdown_it.token import Token
 from markdown_it.tree import SyntaxTreeNode
@@ -954,7 +953,7 @@ def render_link_url(
             if "classes" in conversion:
                 ref_node["classes"].extend(conversion["classes"])
 
-        ref_node["refuri"] = escapeHtml(uri)
+        ref_node["refuri"] = uri
         if implicit_text is not None:
             with self.current_node_context(ref_node, append=True):
                 self.current_node.append(nodes.Text(implicit_text))

tests/test_renderers/fixtures/docutil_syntax_elements.md

@@ -747,3 +747,33 @@ a = 1
         <paragraph>
             <reference refname="target">
 .
+
+URL with ampersand in query string
+.
+[link](https://example.com/search?q=foo&bar=baz)
+.
+<document source="notset">
+    <paragraph>
+        <reference refuri="https://example.com/search?q=foo&bar=baz">
+            link
+.
+
+URL with angle brackets (percent-encoded by normalizeLink, not HTML-escaped)
+.
+[link](https://example.com/path<with>brackets)
+.
+<document source="notset">
+    <paragraph>
+        <reference refuri="https://example.com/path%3Cwith%3Ebrackets">
+            link
+.
+
+URL with double quotes (percent-encoded by normalizeLink, not HTML-escaped)
+.
+[link](https://example.com/path"with"quotes)
+.
+<document source="notset">
+    <paragraph>
+        <reference refuri="https://example.com/path%22with%22quotes">
+            link
+.

tests/test_sphinx/sourcedirs/references/index.md

@@ -8,6 +8,8 @@
 
 [nested *syntax*](https://example.com)
 
+[query params](https://example.com?foo=bar&a=1)
+
 [](title)
 
 [plain text](title)

tests/test_sphinx/test_sphinx_builds/test_references.html

@@ -33,6 +33,11 @@ <h1>
       </em>
      </a>
     </p>
+    <p>
+     <a class="reference external" href="https://example.com?foo=bar&amp;a=1">
+      query params
+     </a>
+    </p>
     <p>
      <a class="reference internal" href="#title">
       <span class="std std-ref">

tests/test_sphinx/test_sphinx_builds/test_references.resolved.xml

@@ -18,6 +18,9 @@
                 nested 
                 <emphasis>
                     syntax
+        <paragraph>
+            <reference refuri="https://example.com?foo=bar&a=1">
+                query params
         <paragraph>
             <reference internal="True" refid="title">
                 <inline classes="std std-ref">

tests/test_sphinx/test_sphinx_builds/test_references.xml

@@ -18,6 +18,9 @@
                 nested 
                 <emphasis>
                     syntax
+        <paragraph>
+            <reference refuri="https://example.com?foo=bar&a=1">
+                query params
         <paragraph>
             <pending_xref refdoc="index" refdomain="True" refexplicit="False" reftarget="title" reftype="myst">
                 <inline classes="xref myst">