Extract TOC anchors from rendered HTML, add smooth scroll and scrollbar fix

- Docs TOC now extracts heading IDs from rendered HTML instead of
  re-deriving slugs from raw markdown, ensuring anchors always match
- Decode HTML entities in TOC titles (e.g. & → &)
- Add smooth scrollIntoView for TOC links on both plugin and docs pages
- Add scroll-mt-20 to plugin article headings for fragment spacing
- Use data-flux-scroll-unlock attribute to compensate for custom
  scrollbar width when Flux locks scroll

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: simonhamp

app/Http/Controllers/ShowDocumentationController.php

@@ -104,7 +104,7 @@ protected function getPageProperties($platform, $version, $page = null): array
         $pageProperties['content'] = CommonMark::convertToHtml($document->body(), [
             'user' => auth()->user(),
         ]);
-        $pageProperties['tableOfContents'] = $this->extractTableOfContents($document->body());
+        $pageProperties['tableOfContents'] = $this->extractTableOfContents($pageProperties['content']);
 
         $navigation = $this->getNavigation($platform, $version);
         $pageProperties['navigation'] = Menu::build($navigation, function (Menu $menu, $nav): void {
@@ -386,21 +386,18 @@ protected function flattenNavigationPages(array $navigation): array
         return $pages;
     }
 
-    protected function extractTableOfContents(string $document): array
+    protected function extractTableOfContents(string $html): array
     {
-        // Remove code blocks which might contain headers.
-        $document = preg_replace('/```[a-z]*\s(.*?)```/s', '', $document);
+        if (! preg_match_all('/<(h[23])\s+id="([^"]+)"[^>]*>(.*?)<\/\1>/si', $html, $matches, PREG_SET_ORDER)) {
+            return [];
+        }
 
-        return collect(explode(PHP_EOL, $document))
-            ->reject(function (string $line) {
-                // Only search for level 2 and 3 headings.
-                return ! Str::startsWith($line, '## ') && ! Str::startsWith($line, '### ');
-            })
-            ->map(function (string $line) {
+        return collect($matches)
+            ->map(function (array $match) {
                 return [
-                    'level' => strlen(trim(Str::before($line, '# '))) + 1,
-                    'title' => $title = htmlspecialchars_decode(trim(Str::after($line, '# '))),
-                    'anchor' => Str::slug(Str::replace('`', 'code', $title)),
+                    'level' => (int) $match[1][1],
+                    'title' => html_entity_decode(trim(strip_tags(preg_replace('/<a\b[^>]*>.*?<\/a>/i', '', $match[3]))), ENT_QUOTES | ENT_HTML5),
+                    'anchor' => $match[2],
                 ];
             })
             ->values()

resources/css/app.css

@@ -79,18 +79,11 @@
     }
 }
 
-/* Compensate for custom scrollbar width when overflow is hidden */
-/* Browser UA sets overflow:hidden on html:has(:modal); Flux JS sets it for menus */
-/* Neither adds padding-right to prevent layout shift with custom 8px scrollbar */
-html:has(dialog:modal) {
+/* Compensate for custom scrollbar width when Flux locks scroll */
+html[data-flux-scroll-unlock] {
     padding-right: 8px !important;
 }
 
-html:has(#mobile-menu-popover:popover-open) {
-    overflow: hidden;
-    padding-right: 8px;
-}
-
 /* Scrollbar width */
 ::-webkit-scrollbar {
     height: 8px;

resources/views/components/plugin-toc.blade.php

@@ -27,6 +27,7 @@
                 <template x-for="heading in headings" :key="heading.id">
                     <a
                         :href="'#' + heading.id"
+                        x-on:click.prevent="document.getElementById(heading.id)?.scrollIntoView({ behavior: 'smooth', block: 'start' })"
                         :class="heading.level === 2 ? 'pl-2' : 'pl-5'"
                         class="rounded-md px-2 py-1.5 text-xs transition hover:bg-zinc-100 dark:text-white/80 dark:hover:bg-zinc-700"
                         x-text="heading.text"

resources/views/docs/index.blade.php

@@ -69,6 +69,7 @@
                             @foreach ($tableOfContents as $item)
                                 <a
                                     href="#{{ $item['anchor'] }}"
+                                    x-on:click.prevent="document.getElementById('{{ $item['anchor'] }}')?.scrollIntoView({ behavior: 'smooth', block: 'start' })"
                                     @class([
                                         'rounded-md px-2 py-1.5 text-xs transition hover:bg-zinc-100 dark:text-white/80 dark:hover:bg-zinc-700',
                                         'pl-2' => $item['level'] == 2,

resources/views/plugin-show.blade.php

@@ -117,7 +117,7 @@ class="font-mono text-2xl font-bold sm:text-3xl"
                                 })
                             }
                         "
-                        class="prose min-w-0 max-w-none grow text-gray-600 dark:text-gray-400 dark:prose-headings:text-white"
+                        class="prose min-w-0 max-w-none grow text-gray-600 prose-headings:scroll-mt-20 dark:text-gray-400 dark:prose-headings:text-white"
                         aria-labelledby="plugin-title"
                     >
                         @if ($plugin->readme_html)

tests/Feature/DocumentationTableOfContentsTest.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Http\Controllers\ShowDocumentationController;
+use Tests\TestCase;
+
+class DocumentationTableOfContentsTest extends TestCase
+{
+    public function test_extracts_headings_from_rendered_html(): void
+    {
+        $html = '<h2 id="installation"><a href="#installation"><span>#</span></a>Installation</h2>'
+            .'<p>Some text.</p>'
+            .'<h3 id="sub-heading"><a href="#sub-heading"><span>#</span></a>Sub Heading</h3>';
+
+        $controller = new ShowDocumentationController;
+
+        $result = $this->invokeMethod($controller, 'extractTableOfContents', [$html]);
+
+        $this->assertCount(2, $result);
+        $this->assertEquals(['level' => 2, 'title' => 'Installation', 'anchor' => 'installation'], $result[0]);
+        $this->assertEquals(['level' => 3, 'title' => 'Sub Heading', 'anchor' => 'sub-heading'], $result[1]);
+    }
+
+    public function test_anchors_match_heading_ids_for_inline_code(): void
+    {
+        $html = '<h2 id="using-codeconfigcode"><a href="#using-codeconfigcode"><span>#</span></a>Using <code>config()</code></h2>';
+
+        $controller = new ShowDocumentationController;
+
+        $result = $this->invokeMethod($controller, 'extractTableOfContents', [$html]);
+
+        $this->assertCount(1, $result);
+        $this->assertEquals('using-codeconfigcode', $result[0]['anchor']);
+        $this->assertEquals('Using config()', $result[0]['title']);
+    }
+
+    public function test_returns_empty_array_when_no_headings(): void
+    {
+        $html = '<p>Just a paragraph.</p>';
+
+        $controller = new ShowDocumentationController;
+
+        $result = $this->invokeMethod($controller, 'extractTableOfContents', [$html]);
+
+        $this->assertEmpty($result);
+    }
+
+    public function test_decodes_html_entities_in_title(): void
+    {
+        $html = '<h2 id="installation-amp-setup"><a href="#installation-amp-setup"><span>#</span></a>Installation &amp; Setup</h2>';
+
+        $controller = new ShowDocumentationController;
+
+        $result = $this->invokeMethod($controller, 'extractTableOfContents', [$html]);
+
+        $this->assertCount(1, $result);
+        $this->assertEquals('Installation & Setup', $result[0]['title']);
+    }
+
+    public function test_ignores_h1_and_h4_headings(): void
+    {
+        $html = '<h1 id="title"><a href="#title"><span>#</span></a>Title</h1>'
+            .'<h2 id="section"><a href="#section"><span>#</span></a>Section</h2>'
+            .'<h4 id="deep"><a href="#deep"><span>#</span></a>Deep</h4>';
+
+        $controller = new ShowDocumentationController;
+
+        $result = $this->invokeMethod($controller, 'extractTableOfContents', [$html]);
+
+        $this->assertCount(1, $result);
+        $this->assertEquals('section', $result[0]['anchor']);
+    }
+
+    /**
+     * @param  array<mixed>  $args
+     */
+    protected function invokeMethod(object $object, string $method, array $args = []): mixed
+    {
+        $reflection = new \ReflectionMethod($object, $method);
+
+        return $reflection->invoke($object, ...$args);
+    }
+}