Merge pull request #747 from phpDocumentor/feature/link-to-page

[FEATURE] Support Hyperlinks to local pages in rst and md
phpDocumentor · Dec 13, 2023 · 437edd1 · 437edd1
2 parents e130f50 + 69769f7
commit 437edd1
Show file tree

Hide file tree

Showing 22 changed files with 242 additions and 17 deletions.
diff --git a/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php b/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php
@@ -16,6 +16,7 @@
 use Psr\Log\LoggerInterface;
 use RuntimeException;
 
+use function ltrim;
 use function md5;
 use function sprintf;
 use function strtolower;
@@ -54,7 +55,7 @@ public function parse(ParserContext $parserContext, string $contents): DocumentN
 
     private function parseDocument(NodeWalker $walker, string $hash): DocumentNode
     {
-        $document = new DocumentNode($hash, $this->getParserContext()->getCurrentAbsolutePath());
+        $document = new DocumentNode($hash, ltrim($this->getParserContext()->getCurrentAbsolutePath(), '/'));
         $this->document = $document;
 
         while ($event = $walker->next()) {

diff --git a/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php b/packages/guides-markdown/src/Markdown/Parsers/InlineParsers/LinkParser.php
@@ -11,7 +11,11 @@
 use Psr\Log\LoggerInterface;
 
 use function assert;
-use function is_string;
+use function filter_var;
+use function str_ends_with;
+use function substr;
+
+use const FILTER_VALIDATE_URL;
 
 /** @extends AbstractInlineTextDecoratorParser<HyperLinkNode> */
 final class LinkParser extends AbstractInlineTextDecoratorParser
@@ -32,11 +36,14 @@ protected function getType(): string
     protected function createInlineNode(CommonMarkNode $commonMarkNode, string|null $content): InlineNode
     {
         assert($commonMarkNode instanceof Link);
-        if (is_string($content)) {
-            return new HyperLinkNode($content, $commonMarkNode->getUrl());
+
+        $content ??= $commonMarkNode->getUrl();
+        $url =  $commonMarkNode->getUrl();
+        if (str_ends_with($url, '.md') && filter_var($url, FILTER_VALIDATE_URL) === false) {
+            $url = substr($url, 0, -3);
         }
 
-        return new HyperLinkNode($commonMarkNode->getUrl(), $commonMarkNode->getUrl());
+        return new HyperLinkNode($content, $url);
     }
 
     protected function supportsCommonMarkNode(CommonMarkNode $commonMarkNode): bool

diff --git a/...ructured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousPhraseRule.php b/...ructured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousPhraseRule.php
@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -25,7 +25,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::BACKTICK;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLinkNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): AbstractLinkInlineNode|null
     {
         $text = '';
         $embeddedUrl = null;
@@ -64,7 +64,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLink
         return null;
     }
 
-    private function createAnonymousReference(BlockContext $blockContext, string $link, string|null $embeddedUrl): HyperLinkNode
+    private function createAnonymousReference(BlockContext $blockContext, string $link, string|null $embeddedUrl): AbstractLinkInlineNode
     {
         $node = $this->createReference($blockContext, $link, $embeddedUrl, false);
         $blockContext->getDocumentParserContext()->pushAnonymous($link);

diff --git a/...tured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousReferenceRule.php b/...tured-text/src/RestructuredText/Parser/Productions/InlineRules/AnonymousReferenceRule.php
@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -26,7 +26,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::ANONYMOUSE_REFERENCE;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLinkNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): AbstractLinkInlineNode|null
     {
         $node = $this->createAnonymousReference(
             $blockContext,
@@ -37,7 +37,7 @@ public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLink
         return $node;
     }
 
-    private function createAnonymousReference(BlockContext $blockContext, string $link): HyperLinkNode
+    private function createAnonymousReference(BlockContext $blockContext, string $link): AbstractLinkInlineNode
     {
         $node = $this->createReference($blockContext, $link, null, false);
         $blockContext->getDocumentParserContext()->pushAnonymous($link);

diff --git a/...s-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php b/...s-restructured-text/src/RestructuredText/Parser/Productions/InlineRules/ReferenceRule.php
@@ -4,28 +4,42 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
+use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
 use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
+use function filter_var;
 use function preg_replace;
+use function str_ends_with;
 use function str_replace;
+use function substr;
 use function trim;
 
+use const FILTER_VALIDATE_URL;
+
 abstract class ReferenceRule extends AbstractInlineRule
 {
-    protected function createReference(BlockContext $blockContext, string $link, string|null $embeddedUrl = null, bool $registerLink = true): HyperLinkNode
+    protected function createReference(BlockContext $blockContext, string $link, string|null $embeddedUrl = null, bool $registerLink = true): AbstractLinkInlineNode
     {
         // the link may have a new line in it, so we need to strip it
         // before setting the link and adding a token to be replaced
         $link = str_replace("\n", ' ', $link);
         $link = trim(preg_replace('/\s+/', ' ', $link) ?? '');
 
+        $targetLink = $embeddedUrl ?? $link;
+        if (str_ends_with($targetLink, '.rst') && filter_var($targetLink, FILTER_VALIDATE_URL) === false) {
+            $targetLink = substr($targetLink, 0, -4);
+
+            return new DocReferenceNode($targetLink, $link);
+        }
+
         if ($registerLink && $embeddedUrl !== null) {
             $blockContext->getDocumentParserContext()->setLink($link, $embeddedUrl);
         }
 
-        return new HyperLinkNode($link, $embeddedUrl ?? $link);
+        return new HyperLinkNode($link, $targetLink);
     }
 
     protected function parseEmbeddedUrl(InlineLexer $lexer): string|null

diff --git a/...ructured-text/src/RestructuredText/Parser/Productions/InlineRules/StandaloneEmailRule.php b/...ructured-text/src/RestructuredText/Parser/Productions/InlineRules/StandaloneEmailRule.php
@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -24,7 +24,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::EMAIL;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLinkNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): AbstractLinkInlineNode|null
     {
         $value = $lexer->token?->value ?? '';
         $node = $this->createReference($blockContext, $value, $value, false);

diff --git a/...ured-text/src/RestructuredText/Parser/Productions/InlineRules/StandaloneHyperlinkRule.php b/...ured-text/src/RestructuredText/Parser/Productions/InlineRules/StandaloneHyperlinkRule.php
@@ -4,7 +4,7 @@
 
 namespace phpDocumentor\Guides\RestructuredText\Parser\Productions\InlineRules;
 
-use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\AbstractLinkInlineNode;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineLexer;
 
@@ -24,7 +24,7 @@ public function applies(InlineLexer $lexer): bool
         return $lexer->token?->type === InlineLexer::HYPERLINK;
     }
 
-    public function apply(BlockContext $blockContext, InlineLexer $lexer): HyperLinkNode|null
+    public function apply(BlockContext $blockContext, InlineLexer $lexer): AbstractLinkInlineNode|null
     {
         $value = $lexer->token?->value ?? '';
         $node = $this->createReference($blockContext, $value, $value, false);

diff --git a/packages/guides/resources/config/guides.php b/packages/guides/resources/config/guides.php
@@ -30,6 +30,7 @@
 use phpDocumentor\Guides\ReferenceResolvers\ExternalReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\InterlinkReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\InternalReferenceResolver;
+use phpDocumentor\Guides\ReferenceResolvers\PageHyperlinkResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ReferenceResolverPreRender;
 use phpDocumentor\Guides\ReferenceResolvers\SluggerAnchorReducer;
@@ -124,6 +125,8 @@
 
         ->set(AnchorHyperlinkResolver::class)
 
+        ->set(PageHyperlinkResolver::class)
+
         ->set(AnchorReferenceResolver::class)
 
         ->set(InternalReferenceResolver::class)

diff --git a/packages/guides/src/ReferenceResolvers/PageHyperlinkResolver.php b/packages/guides/src/ReferenceResolvers/PageHyperlinkResolver.php
@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Guides\ReferenceResolvers;
+
+use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
+use phpDocumentor\Guides\Nodes\Inline\LinkInlineNode;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
+
+use function str_ends_with;
+use function strlen;
+use function substr;
+
+/**
+ * Resolves named and anonymous references to source files
+ *
+ * `Link Text <../page.rst>`_ or [Link Text](path/to/another/page.md)
+ */
+class PageHyperlinkResolver implements ReferenceResolver
+{
+    // Named links and anchors take precedence
+    public final const PRIORITY = -200;
+
+    public function __construct(
+        private readonly UrlGeneratorInterface $urlGenerator,
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
+    }
+
+    public function resolve(LinkInlineNode $node, RenderContext $renderContext): bool
+    {
+        if (!$node instanceof HyperLinkNode) {
+            return false;
+        }
+
+        $canonicalDocumentName = $this->documentNameResolver->canonicalUrl($renderContext->getDirName(), $node->getTargetReference());
+        if (str_ends_with($canonicalDocumentName, '.' . $renderContext->getOutputFormat())) {
+            $canonicalDocumentName = substr($canonicalDocumentName, 0, 0 - strlen('.' . $renderContext->getOutputFormat()));
+        }
+
+        $document = $renderContext->getProjectNode()->findDocumentEntry($canonicalDocumentName);
+        if ($document === null) {
+            return false;
+        }
+
+        $node->setUrl($this->urlGenerator->generateCanonicalOutputUrl($renderContext, $document->getFile()));
+        if ($node->getValue() === '') {
+            $node->setValue($document->getTitle()->toString());
+        }
+
+        return true;
+    }
+
+    public static function getPriority(): int
+    {
+        return self::PRIORITY;
+    }
+}
diff --git a/tests/Integration/tests/hyperlink-to-page/expected/index.html b/tests/Integration/tests/hyperlink-to-page/expected/index.html
@@ -0,0 +1,16 @@
+<!-- content start -->
+    <div class="section" id="some-file">
+    <h1>Some file</h1>
+
+
+
+<ul>
+    <li><a href="/page1.html">link page 1</a></li>
+
+    <li><a href="/subpages/subpage1.html">link subpage 1</a></li>
+
+</ul>
+
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/hyperlink-to-page/expected/subpages/index.html b/tests/Integration/tests/hyperlink-to-page/expected/subpages/index.html
@@ -0,0 +1,31 @@
+<!-- content start -->
+    <div class="section" id="some-file">
+    <h1>Some file</h1>
+
+            <a id="page1"></a>
+
+
+<ul>
+    <li><a href="/page1.html">link page 1</a></li>
+
+    <li><a href="/subpages/subpage1.html">link subpage 1</a></li>
+
+    <li><a href="/page1.html">link page 1</a></li>
+
+    <li><a href="/page1.html">link page 1</a></li>
+
+    <li><a href="/subpages/subpage1.html">link subpage 1</a></li>
+
+    <li><a href="/page1.html">link page 1</a></li>
+
+    <li><a href="/subpages/index.html#page1">link page 1</a></li>
+
+    <li><a href="/subpages/subpage1.html">link subpage 1</a></li>
+
+    <li><a href="/subpages/index.html#page1">link page 1</a></li>
+
+</ul>
+
+    </div>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/hyperlink-to-page/input/index.rst b/tests/Integration/tests/hyperlink-to-page/input/index.rst
@@ -0,0 +1,6 @@
+Some file
+=========
+
+*   `link page 1 <page1.rst>`_
+
+*   `link subpage 1 <subpages/subpage1.rst>`_
diff --git a/tests/Integration/tests/hyperlink-to-page/input/page1.rst b/tests/Integration/tests/hyperlink-to-page/input/page1.rst
@@ -0,0 +1,2 @@
+Page 1
+======
diff --git a/tests/Integration/tests/hyperlink-to-page/input/subpages/index.rst b/tests/Integration/tests/hyperlink-to-page/input/subpages/index.rst
@@ -0,0 +1,17 @@
+..  _page1:
+
+Some file
+=========
+
+*   `link page 1 </page1.rst>`_
+*   `link subpage 1 <subpage1.rst>`_
+*   `link page 1 <../page1.rst>`_
+
+
+*   `link page 1 </page1.html>`_
+*   `link subpage 1 <subpage1.html>`_
+*   `link page 1 <../page1.html>`_
+
+*   `link page 1 </page1>`_
+*   `link subpage 1 <subpage1>`_
+*   `link page 1 <../page1>`_
diff --git a/tests/Integration/tests/hyperlink-to-page/input/subpages/subpage1.rst b/tests/Integration/tests/hyperlink-to-page/input/subpages/subpage1.rst
@@ -0,0 +1,2 @@
+Subpage 1
+=========
diff --git a/tests/Integration/tests/markdown/link-page-md/expected/index.html b/tests/Integration/tests/markdown/link-page-md/expected/index.html
@@ -0,0 +1,16 @@
+<!-- content start -->
+    <h1>Markdown with links</h1>
+
+<p>This is a Markdown document with some basic formatting.</p>
+
+
+<ul>
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+    <li><p><a href="/subpages/subpage1.html">Subpage 1</a></p></li>
+
+</ul>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/markdown/link-page-md/expected/subpages/index.html b/tests/Integration/tests/markdown/link-page-md/expected/subpages/index.html
@@ -0,0 +1,20 @@
+<!-- content start -->
+    <h1>Markdown with links</h1>
+
+<p>This is a Markdown document with some basic formatting.</p>
+
+
+<ul>
+    <li><p><a href="/subpages/subpage1.html">Subpage 1</a></p></li>
+
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+    <li><p><a href="/page1.html">Page 1</a></p></li>
+
+</ul>
+
+<!-- content end -->
diff --git a/tests/Integration/tests/markdown/link-page-md/input/guides.xml b/tests/Integration/tests/markdown/link-page-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="6.4"/>
+</guides>
diff --git a/tests/Integration/tests/markdown/link-page-md/input/index.md b/tests/Integration/tests/markdown/link-page-md/input/index.md
@@ -0,0 +1,7 @@
+# Markdown with links
+
+This is a Markdown document with some basic formatting. 
+
+* [Page 1](page1.md)
+* [Page 1](/page1.md)
+* [Subpage 1](subpages/subpage1.md)
diff --git a/tests/Integration/tests/markdown/link-page-md/input/page1.md b/tests/Integration/tests/markdown/link-page-md/input/page1.md
@@ -0,0 +1,3 @@
+# Page 1
+
+This is a Markdown document with some basic formatting.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Page 1

		This is a Markdown document with some basic formatting.