[BUGFIX] Prefere anchors over titles in references

References phpDocumentor/guides#970

(cherry picked from commit 1af4aad5403fe743ea46d2996bd85e1ba4cca19f)

Author: linawolf

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)

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,
                 ),
             );
 

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)
     {

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()));

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;
+    }
+}