Fix escape chars in references

phpDocumentor · jaapio · Nov 12, 2025 · Nov 7, 2025 · Nov 12, 2025 · 8f31b48f9602cf5b9f7f74ef637a89049ef40934
commit 8f31b48f9602cf5b9f7f74ef637a89049ef40934
diff --git a/...ides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php b/...ides-restructured-text/src/RestructuredText/Parser/References/EmbeddedReferenceParser.php
@@ -14,14 +14,15 @@
 namespace phpDocumentor\Guides\RestructuredText\Parser\References;
 
 use function preg_match;
+use function str_replace;
 use function trim;
 
 trait EmbeddedReferenceParser
 {
     /**
-     * https://regex101.com/r/KadqKx/1
+     * https://regex101.com/r/8O8N3h/2
      */
-    private string $referenceRegex = '/^(.*?)(<([^<]+)>)?$/s';
+    private string $referenceRegex = '/^(.*?)((?<!\\\\)<([^<]+)(?<!\\\\)>)?$/s';
 
     private function extractEmbeddedReference(string $text): ReferenceData
     {
@@ -37,6 +38,9 @@ private function extractEmbeddedReference(string $text): ReferenceData
             $text = null;
         }
 
-        return new ReferenceData($reference, $text);
+        return new ReferenceData(
+            str_replace(['\\<', '\\>'], ['<', '>'], $reference),
+            $text,
+        );
     }
 }
diff --git a/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php b/packages/guides-restructured-text/tests/unit/Parser/InlineTokenParserTest.php
@@ -174,6 +174,10 @@ public static function inlineNodeProvider(): array
                 '`myref`_',
                 new InlineCompoundNode([new HyperLinkNode('myref', 'myref')]),
             ],
+            'Named Reference, escaped phrase' => [
+                '`myref \<foo\>`_',
+                new InlineCompoundNode([new HyperLinkNode('myref <foo>', 'myref <foo>')]),
+            ],
             'Named Reference, Phrased, With URL' => [
                 '`myref <https://test.com>`_',
                 new InlineCompoundNode([new HyperLinkNode('myref', 'https://test.com')]),

diff --git a/tests/Integration/tests/references/reference-with-escape/expected/index.html b/tests/Integration/tests/references/reference-with-escape/expected/index.html
@@ -8,9 +8,7 @@
 <!-- content start -->
     <div class="section" id="the-head">
     <h1>the &lt;head&gt;</h1>
-
-            <a id="anchor"></a>
-        <p>See also <a href="/index.html#anchor">the &lt;head&gt; of this file</a> or <a href="/index.html#the-head">the &lt;head&gt;</a>.</p>
+        <p>See also this is a complex reference <a href="/index.html#the-head">the &lt;head&gt;</a>.</p>
     </div>
 
 <!-- content end -->

diff --git a/tests/Integration/tests/references/reference-with-escape/input/index.rst b/tests/Integration/tests/references/reference-with-escape/input/index.rst
@@ -1,6 +1,4 @@
-.. _anchor:
-
-the \<head\>
+the <head>
 ============
 
-See also :ref:`the \<head\> of this file <anchor>` or `the \<head\>`_.
+See also this is a complex reference `the \<head\>`_.
diff --git a/tests/Integration/tests/references/reference-with-escape/input/skip b/tests/Integration/tests/references/reference-with-escape/input/skip