Merge pull request #998 from phpDocumentor/backport/1.x/pr-996

[1.x] [BUGFIX] Prefere anchors over titles in references

Author: phpdoc-bot

packages/guides/resources/config/guides.php

@@ -40,6 +40,7 @@
 use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolverPreRender;
 use phpDocumentor\Guides\ReferenceResolvers\SluggerAnchorNormalizer;
+use phpDocumentor\Guides\ReferenceResolvers\TitleReferenceResolver;
 use phpDocumentor\Guides\Renderer\HtmlRenderer;
 use phpDocumentor\Guides\Renderer\InMemoryRendererFactory;
 use phpDocumentor\Guides\Renderer\InterlinkObjectsRenderer;
@@ -146,6 +147,8 @@
 
         ->set(AnchorReferenceResolver::class)
 
+        ->set(TitleReferenceResolver::class)
+
         ->set(InternalReferenceResolver::class)
 
         ->set(DocReferenceResolver::class)

packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php

@@ -88,7 +88,7 @@ public function enterNode(Node $node, CompilerContextInterface $compilerContext)
                     $currentDocument->getFilePath(),
                     $anchorName,
                     $node->getLinkText(),
-                    $node->getLinkType(),
+                    SectionNode::STD_TITLE,
                 ),
             );
 

packages/guides/src/Nodes/SectionNode.php

@@ -19,6 +19,7 @@
 final class SectionNode extends CompoundNode implements LinkTargetNode
 {
     public const STD_LABEL = 'std:label';
+    public const STD_TITLE = 'std:title';
 
     public function __construct(private readonly TitleNode $title)
     {

packages/guides/src/ReferenceResolvers/AnchorHyperlinkResolver.php

@@ -15,6 +15,7 @@
 
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\RenderContext;
 use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
 
@@ -43,7 +44,10 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
         $target = $renderContext->getProjectNode()->getInternalTarget($reducedAnchor);
 
         if ($target === null) {
-            return false;
+            $target = $renderContext->getProjectNode()->getInternalTarget($reducedAnchor, SectionNode::STD_TITLE);
+            if ($target === null) {
+                return false;
+            }
         }
 
         $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getAnchor()));

packages/guides/src/ReferenceResolvers/TitleReferenceResolver.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\ReferenceResolvers;
+
+use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
+use phpDocumentor\Guides\Nodes\SectionNode;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
+
+/**
+ * Resolves references with an anchor URL.
+ *
+ * A link is an anchor if it starts with a hashtag
+ */
+final class TitleReferenceResolver implements ReferenceResolver
+{
+    public final const PRIORITY = -200;
+
+    public function __construct(
+        private readonly AnchorNormalizer $anchorReducer,
+        private readonly UrlGeneratorInterface $urlGenerator,
+    ) {
+    }
+
+    public function resolve(LinkInlineNode $node, RenderContext $renderContext, Messages $messages): bool
+    {
+        if (!$node instanceof ReferenceNode || $node->getInterlinkDomain() !== '') {
+            return false;
+        }
+
+        $reducedAnchor = $this->anchorReducer->reduceAnchor($node->getTargetReference());
+        $target = $renderContext->getProjectNode()->getInternalTarget($reducedAnchor, SectionNode::STD_TITLE);
+
+        if ($target === null) {
+            return false;
+        }
+
+        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $target->getDocumentPath(), $target->getPrefix() . $target->getAnchor()));
+        if ($node->getValue() === '') {
+            $node->setValue($target->getTitle() ?? '');
+        }
+
+        return true;
+    }
+
+    public static function getPriority(): int
+    {
+        return self::PRIORITY;
+    }
+}

tests/Integration/tests/anchor/anchor-to-page/expected/objects.inv.json

@@ -20,28 +20,30 @@
         ]
     },
     "std:label": {
-        "page": [
+        "rst-overview": [
             "-",
             "-",
-            "index.html#page",
-            "Page"
+            "rst-overview.html#rst-overview",
+            "Overview"
         ],
-        "overview": [
+        "sphinx-overview": [
             "-",
             "-",
-            "sphinx-overview.html#overview",
+            "sphinx-overview.html#sphinx-overview",
             "Overview"
-        ],
-        "rst-overview": [
+        ]
+    },
+    "std:title": {
+        "page": [
             "-",
             "-",
-            "rst-overview.html#rst-overview",
-            "Overview"
+            "index.html#page",
+            "Page"
         ],
-        "sphinx-overview": [
+        "overview": [
             "-",
             "-",
-            "sphinx-overview.html#sphinx-overview",
+            "sphinx-overview.html#overview",
             "Overview"
         ]
     }

tests/Integration/tests/confval/confval-name/expected/objects.inv.json

@@ -13,7 +13,8 @@
             "Confval directive"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "confval-directive": [
             "-",
             "-",

tests/Integration/tests/confval/confval-noindex/expected/objects.inv.json

@@ -13,7 +13,8 @@
             "Confval directive"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "confval-directive": [
             "-",
             "-",

tests/Integration/tests/confval/confval-warning/expected/objects.inv.json

@@ -14,16 +14,18 @@
         ]
     },
     "std:label": {
-        "confval-directive": [
+        "demo": [
             "-",
             "-",
-            "index.html#confval-directive",
+            "another.html#demo",
             "Confval directive"
-        ],
-        "demo": [
+        ]
+    },
+    "std:title": {
+        "confval-directive": [
             "-",
             "-",
-            "another.html#demo",
+            "index.html#confval-directive",
             "Confval directive"
         ]
     },

tests/Integration/tests/interlink/inventory_json/expected/objects.inv.json

@@ -37,7 +37,8 @@
             "Subpage 2"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "document-title": [
             "-",
             "-",

tests/Integration/tests/interlink/inventory_ref_json/expected/objects.inv.json

@@ -38,28 +38,36 @@
         ]
     },
     "std:label": {
-        "document-title": [
-            "My Project",
-            "3.1.4",
-            "index.html#document-title",
-            "Document Title"
-        ],
         "my-index": [
             "My Project",
             "3.1.4",
             "index.html#my_index",
             "Document Title"
         ],
-        "page-1": [
+        "my-cool-page": [
             "My Project",
             "3.1.4",
-            "page1.html#page-1",
+            "page1.html#my_cool_page",
             "Page 1"
         ],
-        "my-cool-page": [
+        "another-cool-page": [
             "My Project",
             "3.1.4",
-            "page1.html#my_cool_page",
+            "subfolder\/subpage1.html#another_cool_page",
+            "Subpage 1"
+        ]
+    },
+    "std:title": {
+        "document-title": [
+            "My Project",
+            "3.1.4",
+            "index.html#document-title",
+            "Document Title"
+        ],
+        "page-1": [
+            "My Project",
+            "3.1.4",
+            "page1.html#page-1",
             "Page 1"
         ],
         "page-2": [
@@ -80,12 +88,6 @@
             "subfolder\/subpage1.html#subpage-1",
             "Subpage 1"
         ],
-        "another-cool-page": [
-            "My Project",
-            "3.1.4",
-            "subfolder\/subpage1.html#another_cool_page",
-            "Subpage 1"
-        ],
         "subpage-2": [
             "My Project",
             "3.1.4",

tests/Integration/tests/meta/config-file/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "title": [
             "Project Title",
             "6.4",

tests/Integration/tests/meta/meta-data/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "document-title": [
             "My Project",
             "3.1.4",

tests/Integration/tests/meta/project-meta-global/expected/objects.inv.json

@@ -13,7 +13,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "a-page": [
             "My Project",
             "3.1.4",

tests/Integration/tests/meta/project-meta/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "document-title": [
             "My Project",
             "3.1.4",

tests/Integration/tests/meta/project-title-override-warning/expected/objects.inv.json

@@ -13,7 +13,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "a-page": [
             "My Project",
             "3.1.4",

tests/Integration/tests/meta/project-title/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "document-title": [
             "My Project",
             "-",

tests/Integration/tests/meta/settings/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Document Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "document-title": [
             "My Project",
             "3.1.4",

tests/Integration/tests/numeral-rst/expected/objects.inv.json

@@ -13,7 +13,8 @@
             "Some Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "page-not-found-404": [
             "-",
             "-",

tests/Integration/tests/option/expected/objects.inv.json

@@ -7,7 +7,8 @@
             "Some Title"
         ]
     },
-    "std:label": {
+    "std:label": [],
+    "std:title": {
         "some-title": [
             "-",
             "-",

tests/Integration/tests/references/reference-to-anchor/expected/anotherPage.html

@@ -0,0 +1,14 @@
+<!-- content start -->
+    <div class="section" id="another-page">
+            <h1>Another Page</h1>
+
+    <p>Lorem Ipsum</p>
+
+            <div class="section" id="flexforms">
+            <h2>FlexForms</h2>
+
+    <p><a href="index.html#flexforms">FlexForms</a></p>
+
+    </div>
+    </div>
+<!-- content end -->