From 3ad29c25e3616f702ef6a211c6f90fed7d089bf3 Mon Sep 17 00:00:00 2001
From: Simon Hamp <simon.hamp@me.com>
Date: Sun, 29 Mar 2026 14:20:43 +0100
Subject: [PATCH 1/2] Collapse TOC into sticky popover button on plugin and
 docs pages

Replaces inline table of contents with a Flux dropdown/popover button
that sticks to the top-right of the content area. Applied to both
plugin detail pages (Alpine-driven dynamic headings) and docs pages
(server-side TOC data). Adds scrollbar width compensation CSS for
modal and popover overlay states.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 resources/css/app.css                         |  9 ++-
 .../docs/toc-and-sponsors.blade.php           | 29 ---------
 .../views/components/plugin-toc.blade.php     | 33 +++++-----
 resources/views/docs/index.blade.php          | 59 +++++++++--------
 resources/views/plugin-show.blade.php         | 64 ++++++++++---------
 5 files changed, 91 insertions(+), 103 deletions(-)

diff --git a/resources/css/app.css b/resources/css/app.css
index 601e0ffa..31eee117 100644
--- a/resources/css/app.css
+++ b/resources/css/app.css
@@ -79,9 +79,16 @@
     }
 }
 
-/* Prevents scrollbars from appearing when a popover is open */
+/* 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) {
+    padding-right: 8px !important;
+}
+
 html:has(#mobile-menu-popover:popover-open) {
     overflow: hidden;
+    padding-right: 8px;
 }
 
 /* Scrollbar width */
diff --git a/resources/views/components/docs/toc-and-sponsors.blade.php b/resources/views/components/docs/toc-and-sponsors.blade.php
index a20a78ca..528919a5 100644
--- a/resources/views/components/docs/toc-and-sponsors.blade.php
+++ b/resources/views/components/docs/toc-and-sponsors.blade.php
@@ -1,35 +1,6 @@
 {{-- Copy as Markdown Button --}}
 <x-docs.copy-markdown-button />
 
-{{-- On this page --}}
-<h3 class="flex items-center gap-1.5 text-sm opacity-60">
-    {{-- Icon --}}
-    <x-icons.stacked-lines class="size-[18px]" />
-
-    {{-- Label --}}
-    <div>On this page</div>
-</h3>
-
-{{-- Table of contents --}}
-@if (count($tableOfContents) > 0)
-    <div
-        class="mt-4 flex min-h-20 flex-col space-y-2 overflow-y-auto overflow-x-hidden border-l text-xs dark:border-l-white/15"
-    >
-        @foreach ($tableOfContents as $item)
-            <a
-                href="#{{ $item['anchor'] }}"
-                @class([
-                    'transition duration-300 ease-in-out will-change-transform hover:translate-x-0.5 hover:text-violet-400 hover:opacity-100 dark:text-white/80',
-                    'pb-1 pl-3' => $item['level'] == 2,
-                    'py-1 pl-6' => $item['level'] == 3,
-                ])
-            >
-                {{ $item['title'] }}
-            </a>
-        @endforeach
-    </div>
-@endif
-
 <div
     class="mt-3 max-w-52 border-t border-t-black/20 pt-5 dark:border-t-white/15"
 >
diff --git a/resources/views/components/plugin-toc.blade.php b/resources/views/components/plugin-toc.blade.php
index ad14bdf3..c7caa739 100644
--- a/resources/views/components/plugin-toc.blade.php
+++ b/resources/views/components/plugin-toc.blade.php
@@ -15,21 +15,24 @@
     }"
     x-show="headings.length > 0"
     x-cloak
-    class="mb-6"
 >
-    <h3 class="flex items-center gap-1.5 text-sm opacity-60">
-        <x-icons.stacked-lines class="size-[18px]" />
-        <div>On this page</div>
-    </h3>
+    <flux:dropdown position="bottom" align="end">
+        <flux:button variant="filled" size="sm" class="!rounded-full">
+            <x-icons.stacked-lines class="size-4" />
+            On this page
+        </flux:button>
 
-    <div class="mt-4 flex flex-col space-y-2 overflow-y-auto overflow-x-hidden border-l text-xs dark:border-l-white/15">
-        <template x-for="heading in headings" :key="heading.id">
-            <a
-                :href="'#' + heading.id"
-                :class="heading.level === 2 ? 'pb-1 pl-3' : 'py-1 pl-6'"
-                class="transition duration-300 ease-in-out will-change-transform hover:translate-x-0.5 hover:text-violet-400 hover:opacity-100 dark:text-white/80"
-                x-text="heading.text"
-            ></a>
-        </template>
-    </div>
+        <flux:popover class="w-64">
+            <nav class="flex max-h-80 flex-col gap-0.5 overflow-y-auto">
+                <template x-for="heading in headings" :key="heading.id">
+                    <a
+                        :href="'#' + heading.id"
+                        :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"
+                    ></a>
+                </template>
+            </nav>
+        </flux:popover>
+    </flux:dropdown>
 </div>
diff --git a/resources/views/docs/index.blade.php b/resources/views/docs/index.blade.php
index 71d16f22..05aaed50 100644
--- a/resources/views/docs/index.blade.php
+++ b/resources/views/docs/index.blade.php
@@ -53,37 +53,40 @@
         {{-- Copy as Markdown Button --}}
         <x-docs.copy-markdown-button />
 
-        <div>
-            <h3 class="inline-flex items-center gap-1.5 text-sm opacity-50">
-                {{-- Icon --}}
-                <x-icons.stacked-lines class="size-[18px]" />
-                {{-- Label --}}
-                <div>On this page</div>
-            </h3>
-            @if (count($tableOfContents) > 0)
-                <div
-                    class="mt-2 flex flex-col space-y-2 border-l text-xs dark:border-l-white/15"
-                >
-                    @foreach ($tableOfContents as $item)
-                        <a
-                            href="#{{ $item['anchor'] }}"
-                            @class([
-                                'transition duration-300 ease-in-out will-change-transform hover:translate-x-0.5 hover:text-violet-400 hover:opacity-100 dark:text-white/80',
-                                'pb-1 pl-3' => $item['level'] == 2,
-                                'py-1 pl-6' => $item['level'] == 3,
-                            ])
-                        >
-                            {{ $item['title'] }}
-                        </a>
-                    @endforeach
-                </div>
-            @endif
-        </div>
-
     </div>
 
+    @if (count($tableOfContents) > 0)
+        <div class="sticky top-20 z-10 mt-8 mb-4 flex justify-end">
+            <div class="rounded-full bg-white shadow-sm dark:bg-zinc-800">
+                <flux:dropdown position="bottom" align="end">
+                    <flux:button variant="filled" size="sm" class="!rounded-full">
+                        <x-icons.stacked-lines class="size-4" />
+                        On this page
+                    </flux:button>
+
+                    <flux:popover class="w-64">
+                        <nav class="flex max-h-80 flex-col gap-0.5 overflow-y-auto">
+                            @foreach ($tableOfContents as $item)
+                                <a
+                                    href="#{{ $item['anchor'] }}"
+                                    @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,
+                                        'pl-5' => $item['level'] == 3,
+                                    ])
+                                >
+                                    {{ $item['title'] }}
+                                </a>
+                            @endforeach
+                        </nav>
+                    </flux:popover>
+                </flux:dropdown>
+            </div>
+        </div>
+    @endif
+
     <div
-        class="prose dark:prose-invert prose-headings:scroll-mt-20 prose-headings:text-gray-800 sm:prose-headings:scroll-mt-32 dark:prose-headings:text-gray-50 mt-8 max-w-none"
+        class="prose dark:prose-invert prose-headings:scroll-mt-20 prose-headings:text-gray-800 sm:prose-headings:scroll-mt-32 dark:prose-headings:text-gray-50 max-w-none"
     >
         {!! $content !!}
     </div>
diff --git a/resources/views/plugin-show.blade.php b/resources/views/plugin-show.blade.php
index 8bfd2888..efea1b6f 100644
--- a/resources/views/plugin-show.blade.php
+++ b/resources/views/plugin-show.blade.php
@@ -95,38 +95,42 @@ class="font-mono text-2xl font-bold sm:text-3xl"
         <x-divider />
 
         <div class="mt-2 flex flex-col-reverse gap-8 lg:flex-row lg:items-start">
-            {{-- Main content - README --}}
-            <div class="min-w-0 grow">
-                @if ($plugin->readme_html)
-                    <x-plugin-toc />
-                @endif
-
-                <article
-                    x-init="
-                        () => {
-                            motion.inView($el, () => {
-                                gsap.fromTo(
-                                    $el,
-                                    { autoAlpha: 0, y: 5 },
-                                    { autoAlpha: 1, y: 0, duration: 0.7, ease: 'power1.out' },
-                                )
-                            })
-                        }
-                    "
-                    class="prose min-w-0 max-w-none grow text-gray-600 dark:text-gray-400 dark:prose-headings:text-white"
-                    aria-labelledby="plugin-title"
-                >
+                {{-- Main content - README --}}
+                <div class="min-w-0 grow">
                     @if ($plugin->readme_html)
-                        {!! $plugin->readme_html !!}
-                @else
-                    <div class="rounded-xl border border-gray-200 bg-gray-50 p-8 text-center dark:border-gray-700 dark:bg-slate-800/50">
-                        <p class="text-gray-500 dark:text-gray-400">
-                            README not available yet.
-                        </p>
-                    </div>
+                        <div class="sticky top-20 z-10 mb-4 flex justify-end">
+                            <div class="rounded-full bg-white shadow-sm dark:bg-zinc-800">
+                                <x-plugin-toc />
+                            </div>
+                        </div>
                     @endif
-                </article>
-            </div>
+
+                    <article
+                        x-init="
+                            () => {
+                                motion.inView($el, () => {
+                                    gsap.fromTo(
+                                        $el,
+                                        { autoAlpha: 0, y: 5 },
+                                        { autoAlpha: 1, y: 0, duration: 0.7, ease: 'power1.out' },
+                                    )
+                                })
+                            }
+                        "
+                        class="prose min-w-0 max-w-none grow text-gray-600 dark:text-gray-400 dark:prose-headings:text-white"
+                        aria-labelledby="plugin-title"
+                    >
+                        @if ($plugin->readme_html)
+                            {!! $plugin->readme_html !!}
+                        @else
+                            <div class="rounded-xl border border-gray-200 bg-gray-50 p-8 text-center dark:border-gray-700 dark:bg-slate-800/50">
+                                <p class="text-gray-500 dark:text-gray-400">
+                                    README not available yet.
+                                </p>
+                            </div>
+                        @endif
+                    </article>
+                </div>
 
             {{-- Sidebar - Plugin details --}}
             <aside

From f820172adb44ec016d12d2e33034e2be8f93dd76 Mon Sep 17 00:00:00 2001
From: Simon Hamp <simon.hamp@me.com>
Date: Sun, 29 Mar 2026 14:41:09 +0100
Subject: [PATCH 2/2] Extract TOC anchors from rendered HTML, add smooth scroll
 and scrollbar fix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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. &amp; → &)
- 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>
---
 .../ShowDocumentationController.php           | 23 +++--
 resources/css/app.css                         | 11 +--
 .../views/components/plugin-toc.blade.php     |  1 +
 resources/views/docs/index.blade.php          |  1 +
 resources/views/plugin-show.blade.php         |  2 +-
 .../DocumentationTableOfContentsTest.php      | 84 +++++++++++++++++++
 6 files changed, 99 insertions(+), 23 deletions(-)
 create mode 100644 tests/Feature/DocumentationTableOfContentsTest.php

diff --git a/app/Http/Controllers/ShowDocumentationController.php b/app/Http/Controllers/ShowDocumentationController.php
index bdcc697a..8dda7bb3 100644
--- a/app/Http/Controllers/ShowDocumentationController.php
+++ b/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()
diff --git a/resources/css/app.css b/resources/css/app.css
index 31eee117..b87db60d 100644
--- a/resources/css/app.css
+++ b/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;
diff --git a/resources/views/components/plugin-toc.blade.php b/resources/views/components/plugin-toc.blade.php
index c7caa739..f4803e5a 100644
--- a/resources/views/components/plugin-toc.blade.php
+++ b/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"
diff --git a/resources/views/docs/index.blade.php b/resources/views/docs/index.blade.php
index 05aaed50..a1034f1b 100644
--- a/resources/views/docs/index.blade.php
+++ b/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,
diff --git a/resources/views/plugin-show.blade.php b/resources/views/plugin-show.blade.php
index efea1b6f..f76a8f3f 100644
--- a/resources/views/plugin-show.blade.php
+++ b/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)
diff --git a/tests/Feature/DocumentationTableOfContentsTest.php b/tests/Feature/DocumentationTableOfContentsTest.php
new file mode 100644
index 00000000..0192fd12
--- /dev/null
+++ b/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);
+    }
+}