fix: resolve cross-page fragment links in markdown

packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php

@@ -22,7 +22,9 @@
 use Psr\Log\LoggerInterface;
 
 use function assert;
+use function explode;
 use function filter_var;
+use function str_contains;
 use function str_ends_with;
 use function substr;
 
@@ -49,11 +51,20 @@ protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null
     {
         assert($commonMarkNode instanceof Link);
 
-        $url =  $commonMarkNode->getUrl();
+        $url = $commonMarkNode->getUrl();
+        $anchor = '';
+        if (str_contains($url, '#')) {
+            $exploded = explode('#', $url, 2);
+            $url = $exploded[0];
+            $anchor = '#' . $exploded[1];
+        }
+
         if (str_ends_with($url, '.md') && filter_var($url, FILTER_VALIDATE_URL) === false) {
             $url = substr($url, 0, -3);
         }
 
+        $url .= $anchor;
+
         return new HyperLinkNode($content ? [new PlainTextInlineNode($content)] : $children, $url);
     }
 

packages/guides/src/ReferenceResolvers/PageHyperlinkResolver.php

@@ -20,6 +20,8 @@
 use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
 
 use function count;
+use function explode;
+use function str_contains;
 use function str_ends_with;
 use function strlen;
 use function substr;
@@ -46,7 +48,15 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
             return false;
         }
 
-        $canonicalDocumentName = $this->documentNameResolver->canonicalUrl($renderContext->getDirName(), $node->getTargetReference());
+        $targetReference = $node->getTargetReference();
+        $anchor = '';
+        if (str_contains($targetReference, '#')) {
+            $exploded = explode('#', $targetReference, 2);
+            $targetReference = $exploded[0];
+            $anchor = '#' . $exploded[1];
+        }
+
+        $canonicalDocumentName = $this->documentNameResolver->canonicalUrl($renderContext->getDirName(), $targetReference);
         if (str_ends_with($canonicalDocumentName, '.' . $renderContext->getOutputFormat())) {
             $canonicalDocumentName = substr($canonicalDocumentName, 0, 0 - strlen('.' . $renderContext->getOutputFormat()));
         }
@@ -56,7 +66,7 @@ public function resolve(LinkInlineNode $node, RenderContext $renderContext, Mess
             return false;
         }
 
-        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $document->getFile()));
+        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $document->getFile()) . $anchor);
         if (count($node->getChildren()) === 0) {
             $node->addChildNode(new PlainTextInlineNode($document->getTitle()->toString()));
         }

packages/guides/tests/unit/ReferenceResolvers/PageHyperlinkResolverTest.php

@@ -0,0 +1,85 @@
+<?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\DocumentTree\DocumentEntryNode;
+use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\Nodes\TitleNode;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+final class PageHyperlinkResolverTest extends TestCase
+{
+    private RenderContext&MockObject $renderContext;
+    private ProjectNode $projectNode;
+    private MockObject&UrlGeneratorInterface $urlGenerator;
+    private MockObject&DocumentNameResolverInterface $documentNameResolver;
+    private PageHyperlinkResolver $subject;
+
+    protected function setUp(): void
+    {
+        $documentEntry = new DocumentEntryNode('some-document', TitleNode::emptyNode());
+        $this->projectNode = new ProjectNode('some-name');
+        $this->projectNode->addDocumentEntry($documentEntry);
+        $this->renderContext = $this->createMock(RenderContext::class);
+        $this->renderContext->expects(self::any())->method('getProjectNode')->willReturn($this->projectNode);
+        $this->renderContext->method('getDirName')->willReturn('');
+        $this->renderContext->method('getOutputFormat')->willReturn('html');
+        $this->documentNameResolver = self::createMock(DocumentNameResolverInterface::class);
+        $this->urlGenerator = self::createMock(UrlGeneratorInterface::class);
+        $this->subject = new PageHyperlinkResolver($this->urlGenerator, $this->documentNameResolver);
+    }
+
+    #[DataProvider('pathProvider')]
+    public function testPageHyperlinkResolver(string $expected, string $input, string $path): void
+    {
+        $this->documentNameResolver->expects(self::once())->method('canonicalUrl')->with('', $path)->willReturn($path);
+        $node = new HyperLinkNode([], $input);
+        $this->urlGenerator->expects(self::once())->method('generateCanonicalOutputUrl')->willReturn($path);
+        $messages = new Messages();
+        self::assertTrue($this->subject->resolve($node, $this->renderContext, $messages));
+        self::assertEmpty($messages->getWarnings());
+        self::assertEquals($expected, $node->getUrl());
+    }
+
+    public function testDocumentNotFound(): void
+    {
+        $this->documentNameResolver->expects(self::once())->method('canonicalUrl')->with('', 'nonexistent-page')->willReturn('nonexistent-page');
+        $node = new HyperLinkNode([], 'nonexistent-page#anchor');
+        $messages = new Messages();
+        self::assertFalse($this->subject->resolve($node, $this->renderContext, $messages));
+        self::assertEquals('', $node->getUrl());
+    }
+
+    /** @return string[][] */
+    public static function pathProvider(): array
+    {
+        return [
+            'plain' => [
+                'expected' => 'some-document',
+                'input' => 'some-document',
+                'path' => 'some-document',
+            ],
+            'withAnchor' => [
+                'expected' => 'some-document#anchor',
+                'input' => 'some-document#anchor',
+                'path' => 'some-document',
+            ],
+        ];
+    }
+}

tests/Integration/tests/markdown/link-page-fragment-md/expected/index.html

@@ -0,0 +1,12 @@
+<!-- content start -->
+
+<div class="section" id="page-a">
+            <h1>Page A</h1>
+
+    <p>See <a href="/page-b.html#section-two">Section Two on Page B</a>.</p>
+
+
+    <p>See <a href="/page-b.html#page-b">Page B without fragment</a>.</p>
+
+    </div>
+<!-- content end -->

tests/Integration/tests/markdown/link-page-fragment-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+>
+    <project title="Project Title" version="1.0"/>
+</guides>

tests/Integration/tests/markdown/link-page-fragment-md/input/index.md

@@ -0,0 +1,5 @@
+# Page A
+
+See [Section Two on Page B](page-b.md#section-two).
+
+See [Page B without fragment](page-b.md).

tests/Integration/tests/markdown/link-page-fragment-md/input/page-b.md

@@ -0,0 +1,5 @@
+# Page B
+
+## Section Two
+
+Content here.