🐛 FIX: Double encoding ampersand in query params

myst_parser/parsers/docutils_.py

@@ -1,5 +1,6 @@
 """MyST Markdown parser for docutils."""
 
+import re
 from dataclasses import Field
 from typing import (
     Any,
@@ -268,6 +269,10 @@ def parse(self, inputstring: str, document: nodes.document) -> None:
         HTMLTranslator.depart_rubric = depart_rubric_html
         HTMLTranslator.visit_container = visit_container_html
         HTMLTranslator.depart_container = depart_container_html
+        HTMLTranslator.special_chars_no_amp = {  # needed by encode_fixed
+            k: v for k, v in HTMLTranslator.special_characters.items() if k != ord("&")
+        }
+        HTMLTranslator.encode = encode_fixed
 
         self.setup_parse(inputstring, document)
 
@@ -515,3 +520,12 @@ def depart_container_html(self, node: nodes.Node):
     See explanation in `visit_container_html`
     """
     self.body.append("</div>\n")
+
+
+def encode_fixed(self, text: str):
+    """Override the default encode method to prevent `&` characters from getting encoded
+    multiple times.
+    """
+    text = str(text)
+    translated = text.translate(self.special_chars_no_amp)
+    return re.sub(r"(&)(?!amp;)", "&amp;", translated)

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&amp;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&amp;a=1">
+                query params
         <paragraph>
             <pending_xref refdoc="index" refdomain="True" refexplicit="False" reftarget="title" reftype="myst">
                 <inline classes="xref myst">