feat: resolve relative markdown links to internal docs routes (#31)

* feat: resolve relative markdown links to internal docs routes

Convert relative .md links (e.g. installation.md, ../README.md) found
in documentation files to internal /docs/{page} URLs, falling back to
GitHub URLs only for external or unresolvable links.

* fix: rename INFO alert type to NOTE in GitHub alert parser

* chore: update IDE helpers and lock file

Author: loadinglucian

.phpstorm.meta.php

@@ -24282,6 +24282,10 @@ public static function response($callback)
      */
     class DocsViewer extends \Livewire\Component {
             }
+    /**
+     */
+    class CommandIndex extends \Livewire\Component {
+            }
     }
 
 

_ide_helper.php

@@ -81,7 +81,7 @@ private function loadFromPath(string $filePath, string $documentIdentity, string
             return null;
         }
 
-        $html = $this->markdown->toHtml($content);
+        $html = $this->markdown->toHtml($content, $documentIdentity === 'readme' ? null : $titleFallback, $filePath);
         $headings = $this->headingExtractor->extract($html);
         $title = $this->extractTitle($html, $titleFallback);
 

app/Services/DocumentService.php

@@ -45,15 +45,18 @@ public function __construct()
     /**
      * Convert markdown to HTML with GitHub-style alert boxes, code block wrappers, and link transformation.
      */
-    public function toHtml(string $markdown, ?string $currentSection = null): string
-    {
+    public function toHtml(
+        string $markdown,
+        ?string $currentSection = null,
+        ?string $sourceFilePath = null,
+    ): string {
         $markdown = $this->stripMarkdownArtifacts($markdown);
         $html = $this->converter->convert($markdown)->getContent();
         $html = $this->stripContentBeforeH1($html);
         $html = $this->convertGitHubAlerts($html);
         $html = $this->wrapCodeBlocks($html);
 
-        return $this->transformLinks($html, $currentSection);
+        return $this->transformLinks($html, $currentSection, $sourceFilePath);
     }
 
     /**
@@ -104,7 +107,7 @@ private function stripMarkdownArtifacts(string $markdown): string
      * Convert GitHub-style alerts to styled callout boxes.
      *
      * Transforms blockquotes like:
-     *   > [!INFO]
+     *   > [!NOTE]
      *   > Content here
      *
      * Into styled alert boxes with icons using Blade component.
@@ -117,7 +120,7 @@ private function convertGitHubAlerts(string $html): string
         //   ...optional additional block elements (e.g. <p>, <ul>, <pre>)...
         // </blockquote>
         return preg_replace_callback(
-            '/<blockquote>\s*<p>\s*\[!(INFO|IMPORTANT)\]\s*(.*?)<\/p>(.*?)<\/blockquote>/is',
+            '/<blockquote>\s*<p>\s*\[!(NOTE|IMPORTANT)\]\s*(.*?)<\/p>(.*?)<\/blockquote>/is',
             function (array $matches): string {
                 $type = strtolower(trim($matches[1]));
                 $firstParagraph = trim($matches[2]);
@@ -178,11 +181,11 @@ function (array $matches): string {
      * Converts links like `section/file.md` or `/docs/section/page` to full
      * GitHub URLs pointing to the source repository.
      */
-    private function transformLinks(string $html, ?string $currentSection): string
+    private function transformLinks(string $html, ?string $currentSection, ?string $sourceFilePath): string
     {
         return preg_replace_callback(
             '/<a\s+href="([^"]+)"([^>]*)>/i',
-            fn (array $matches): string => $this->transformLink($matches, $currentSection),
+            fn (array $matches): string => $this->transformLink($matches, $currentSection, $sourceFilePath),
             $html
         ) ?? $html;
     }
@@ -195,7 +198,7 @@ private function transformLinks(string $html, ?string $currentSection): string
      *
      * @param  array<int, string>  $matches
      */
-    private function transformLink(array $matches, ?string $currentSection): string
+    private function transformLink(array $matches, ?string $currentSection, ?string $sourceFilePath): string
     {
         $href = $matches[1];
         $attributes = $matches[2];
@@ -212,6 +215,12 @@ private function transformLink(array $matches, ?string $currentSection): string
             return sprintf('<a href="%s"%s>', $internalUrl, $attributes);
         }
 
+        $relativeDocsUrl = $this->resolveRelativeDocsUrl($href, $sourceFilePath);
+
+        if ($relativeDocsUrl !== null) {
+            return sprintf('<a href="%s"%s>', $relativeDocsUrl, $attributes);
+        }
+
         // All other links → GitHub with target="_blank"
         $githubUrl = $this->resolveGitHubUrl($href, $currentSection);
 
@@ -222,6 +231,84 @@ private function transformLink(array $matches, ?string $currentSection): string
         );
     }
 
+    private function resolveRelativeDocsUrl(string $href, ?string $sourceFilePath): ?string
+    {
+        if ($sourceFilePath === null || str_starts_with($href, '/')) {
+            return null;
+        }
+
+        [$path, $fragment] = $this->splitFragment($href);
+
+        if ($path === '' || preg_match('/^[a-z][a-z0-9+.-]*:/i', $path) === 1) {
+            return null;
+        }
+
+        $docsDirectory = config('docs.path');
+
+        if (! is_string($docsDirectory) || $docsDirectory === '') {
+            return null;
+        }
+
+        $absoluteDocsDirectory = str_starts_with($docsDirectory, '/')
+            ? $docsDirectory
+            : base_path($docsDirectory);
+
+        $resolvedDocsDirectory = realpath($absoluteDocsDirectory);
+        $resolvedSourcePath = realpath($sourceFilePath);
+
+        if ($resolvedDocsDirectory === false || $resolvedSourcePath === false) {
+            return null;
+        }
+
+        $sourceDirectory = dirname($resolvedSourcePath);
+        $candidatePath = $path;
+
+        if (! str_ends_with($candidatePath, '.md')) {
+            $candidatePath .= '.md';
+        }
+
+        $resolvedTargetPath = realpath($sourceDirectory.'/'.$candidatePath);
+
+        if ($resolvedTargetPath === false || ! str_ends_with($resolvedTargetPath, '.md')) {
+            return null;
+        }
+
+        $resolvedDocsParentReadme = realpath(dirname($resolvedDocsDirectory).'/README.md');
+
+        if ($resolvedDocsParentReadme !== false && $resolvedTargetPath === $resolvedDocsParentReadme) {
+            return '/'.$fragment;
+        }
+
+        $docsPrefix = rtrim($resolvedDocsDirectory, DIRECTORY_SEPARATOR).DIRECTORY_SEPARATOR;
+
+        if (! str_starts_with($resolvedTargetPath, $docsPrefix)) {
+            return null;
+        }
+
+        $relativeTargetPath = substr($resolvedTargetPath, strlen($docsPrefix));
+        $page = preg_replace('/\.md$/', '', $relativeTargetPath);
+
+        if ($page === null || $page === '' || preg_match('/^[a-z0-9-]+$/', $page) !== 1) {
+            return null;
+        }
+
+        return "/docs/{$page}{$fragment}";
+    }
+
+    /**
+     * @return array{0: string, 1: string}
+     */
+    private function splitFragment(string $href): array
+    {
+        if (! str_contains($href, '#')) {
+            return [$href, ''];
+        }
+
+        [$path, $fragment] = explode('#', $href, 2);
+
+        return [$path, '#'.$fragment];
+    }
+
     /**
      * Determine if a link points to a docs page by path prefix.
      */

app/Services/MarkdownService.php

@@ -39,6 +39,20 @@
         ->assertSeeText('Requirements');
 });
 
+it('converts relative markdown docs links to internal routes', function (): void {
+    app()->forgetInstance(DocsPathService::class);
+    app()->forgetInstance(TocParserService::class);
+    app()->forgetInstance(DocumentService::class);
+
+    $response = $this->get(route('docs.show', ['page' => 'documentation']));
+
+    $response->assertOk()
+        ->assertSee('href="'.route('home').'"', false)
+        ->assertSee('href="'.route('docs.show', ['page' => 'installation']).'"', false)
+        ->assertSee('href="'.route('docs.show', ['page' => 'link-behavior']).'"', false)
+        ->assertSee('href="https://github.com/loadinglucian/deployer-php/blob/main/docs/operations/runbooks.md" target="_blank" rel="noopener noreferrer"', false);
+});
+
 it('redirects missing docs pages to the docs home', function (): void {
     app()->forgetInstance(DocsPathService::class);
     app()->forgetInstance(TocParserService::class);

composer.lock

@@ -1,6 +1,6 @@
 <a name="guides"></a>
 ## Guides
-- [Introduction](README.md)
+- [Introduction](../README.md)
 - [Installation](installation.md)
 - [Link Behavior](link-behavior.md)
 

tests/Feature/DocsSidebarNavigationTest.php

@@ -107,6 +107,23 @@
         ->toContain('<li>Second item</li>');
 });
 
+it('renders note alerts with block content', function (): void {
+    $markdown = <<<'MARKDOWN'
+> [!NOTE]
+> First note callout.
+>
+> - First item
+> - Second item
+MARKDOWN;
+
+    $html = app(MarkdownService::class)->toHtml($markdown);
+
+    expect(substr_count($html, 'dark:border-l-cyan-400'))->toBe(1)
+        ->and($html)
+        ->toContain('<li>First item</li>')
+        ->toContain('<li>Second item</li>');
+});
+
 it('keeps empty github alert markers unchanged when there is no content', function (): void {
     $markdown = <<<'MARKDOWN'
 > [!IMPORTANT]