From 31189afd84b54a69390bef44c2ec005adca62356 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Sat, 10 Oct 2026 03:06:56 +0200
Subject: [PATCH 1/5] fix(chrome): desktop sidebar collapse without a Blazor
 runtime

The collapse and expand buttons toggled SidebarCollapseState through @onclick, so they did nothing on a static export. They are now [data-sidebar-collapse-toggle] buttons handled by shelldocs.js, which flips [data-sidebar-collapsed] on the page shell and remembers the choice in localStorage; it's restored as soon as the script runs, so the sidebar doesn't flash open, and again after Blazor swaps the DOM. The expand toolbar is always rendered in the Sidebar layout and shown by CSS. SidebarCollapseState stays registered, unused.
---
 .../Chrome/DocsSidebarHeader.razor            |  3 +-
 .../Chrome/SidebarCollapseState.cs            |  3 +-
 .../Layouts/DocsLayout.razor                  | 15 ++--
 .../Layouts/DocsLayout.razor.css              | 11 +--
 src/ShellDocs.Components/wwwroot/shelldocs.js | 27 +++++++
 tests/ShellDocs.Tests/SidebarCollapseTests.cs | 72 +++++++++++++++++++
 6 files changed, 113 insertions(+), 18 deletions(-)
 create mode 100644 tests/ShellDocs.Tests/SidebarCollapseTests.cs

diff --git a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
index 1f9bb75..aaab0ca 100644
--- a/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
+++ b/src/ShellDocs.Components/Chrome/DocsSidebarHeader.razor
@@ -1,7 +1,6 @@
 @using ShellIcons.Icons
 @inject ShellDocsOptions Options
 @inject IJSRuntime JS
-@inject SidebarCollapseState Collapse
 
 <div class="docs-sidebar-header">
     <div class="docs-sidebar-brand-row">
@@ -9,7 +8,7 @@
             <BrandLogo />
             <span class="docs-sidebar-brand-name">@(!string.IsNullOrEmpty(Options.SiteName) ? Options.SiteName : "Docs")</span>
         </a>
-        <button type="button" class="docs-sidebar-collapse" @onclick="Collapse.Toggle" aria-label="Collapse sidebar" title="Collapse sidebar">
+        <button type="button" class="docs-sidebar-collapse" data-sidebar-collapse-toggle aria-label="Collapse sidebar" title="Collapse sidebar">
             <PanelLeft StrokeWidth="1.75" />
         </button>
     </div>
diff --git a/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs b/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
index 2b042a1..40b4823 100644
--- a/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
+++ b/src/ShellDocs.Components/Chrome/SidebarCollapseState.cs
@@ -1,7 +1,6 @@
 namespace ShellDocs.Components.Chrome;
 
-// Desktop collapse for the Sidebar layout — persistent, unlike the
-// temporary mobile drawer in MobileNavState.
+// No longer used: the sidebar collapse is driven by shelldocs.js. Kept so existing code compiles.
 public class SidebarCollapseState
 {
     public bool IsCollapsed { get; private set; }
diff --git a/src/ShellDocs.Components/Layouts/DocsLayout.razor b/src/ShellDocs.Components/Layouts/DocsLayout.razor
index 949c168..37ec33b 100644
--- a/src/ShellDocs.Components/Layouts/DocsLayout.razor
+++ b/src/ShellDocs.Components/Layouts/DocsLayout.razor
@@ -1,11 +1,11 @@
 @inherits LayoutComponentBase
-@inject ShellDocs.Components.Chrome.SidebarCollapseState Collapse
 @inject ShellDocsOptions Options
 @inject IJSRuntime JS
-@implements IDisposable
 @using Microsoft.AspNetCore.Components.Sections
 
-<div class="docs-shell docs-shell-@Variant @(Collapse.IsCollapsed ? "docs-sidebar-collapsed" : "")" data-mobile-open="false">
+@* [data-sidebar-collapsed] is flipped by shelldocs.js ([data-sidebar-collapse-toggle]),
+   so collapsing works without a Blazor runtime. *@
+<div class="docs-shell docs-shell-@Variant" data-mobile-open="false" data-sidebar-collapsed="false">
     @if (Options.LayoutVariant == DocsLayoutVariant.TopNav)
     {
         <DocsHeader />
@@ -15,10 +15,11 @@
         <DocsMobileBar />
     }
 
-    @if (Options.LayoutVariant == DocsLayoutVariant.Sidebar && Collapse.IsCollapsed)
+    @if (Options.LayoutVariant == DocsLayoutVariant.Sidebar)
     {
+        @* Shown by CSS while the sidebar is collapsed. *@
         <div class="docs-collapsed-toolbar">
-            <button type="button" class="docs-collapsed-tool" @onclick="Collapse.Toggle" aria-label="Expand sidebar" title="Expand sidebar">
+            <button type="button" class="docs-collapsed-tool" data-sidebar-collapse-toggle aria-label="Expand sidebar" title="Expand sidebar">
                 <ShellIcons.Icons.PanelLeft StrokeWidth="1.75" />
             </button>
             <button type="button" class="docs-collapsed-tool" @onclick="OpenSearch" aria-label="Search" title="Search (⌘K)">
@@ -58,9 +59,5 @@
         _ => "topnav"
     };
 
-    protected override void OnInitialized() => Collapse.OnChange += StateHasChanged;
-
     private Task OpenSearch() => JS.InvokeVoidAsync("shelldocsSearch.open").AsTask();
-
-    public void Dispose() => Collapse.OnChange -= StateHasChanged;
 }
diff --git a/src/ShellDocs.Components/Layouts/DocsLayout.razor.css b/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
index 302ccbd..95442c2 100644
--- a/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
+++ b/src/ShellDocs.Components/Layouts/DocsLayout.razor.css
@@ -156,11 +156,11 @@
         padding: 0 1rem 1rem 1.25rem;
     }
 
-    .docs-shell-sidebar.docs-sidebar-collapsed .docs-sidebar-slot { display: none; }
-    .docs-shell-sidebar.docs-sidebar-collapsed .docs-body {
+    .docs-shell-sidebar[data-sidebar-collapsed="true"] .docs-sidebar-slot { display: none; }
+    .docs-shell-sidebar[data-sidebar-collapsed="true"] .docs-body {
         grid-template-columns: 1fr;
     }
-    .docs-shell-sidebar.docs-sidebar-collapsed .docs-main {
+    .docs-shell-sidebar[data-sidebar-collapsed="true"] .docs-main {
         padding-left: 3rem;
     }
 }
@@ -169,7 +169,7 @@
     .docs-shell-sidebar .docs-body {
         grid-template-columns: var(--sidebar-width) 1fr var(--toc-width);
     }
-    .docs-shell-sidebar.docs-sidebar-collapsed .docs-body {
+    .docs-shell-sidebar[data-sidebar-collapsed="true"] .docs-body {
         grid-template-columns: 1fr var(--toc-width);
     }
 }
@@ -179,7 +179,7 @@
     top: 0.9rem;
     left: 0.9rem;
     z-index: 30;
-    display: flex;
+    display: none;
     gap: 0.25rem;
     background: var(--card);
     border: 1px solid var(--border);
@@ -187,6 +187,7 @@
     box-shadow: 0 1px 2px rgb(0 0 0 / 0.04);
     padding: 0.2rem;
 }
+.docs-shell[data-sidebar-collapsed="true"] .docs-collapsed-toolbar { display: flex; }
 .docs-collapsed-tool {
     display: inline-flex;
     align-items: center;
diff --git a/src/ShellDocs.Components/wwwroot/shelldocs.js b/src/ShellDocs.Components/wwwroot/shelldocs.js
index 07d218c..bbf976c 100644
--- a/src/ShellDocs.Components/wwwroot/shelldocs.js
+++ b/src/ShellDocs.Components/wwwroot/shelldocs.js
@@ -669,6 +669,7 @@ window.shelldocsChrome = (function () {
                     restoreTabs(added[n]);
                     window.shelldocsIframes.init(added[n]);
                     restoreMobileNav(added[n]);
+                    restoreCollapse(added[n]);
                 }
             }
         }).observe(document.documentElement, { childList: true, subtree: true });
@@ -677,6 +678,28 @@ window.shelldocsChrome = (function () {
     /* Mobile nav: hamburgers toggle [data-mobile-open] on the page shell. CSS slides
        in the docs sidebar or shows the home menu; the backdrop, Escape, picking a
        link, or an enhanced navigation closes it. */
+    /* Desktop sidebar collapse: [data-sidebar-collapse-toggle] buttons flip
+       [data-sidebar-collapsed] on the page shell, and the choice is remembered. */
+    var COLLAPSE_KEY = 'shelldocs-sidebar';
+
+    function onCollapseClick(e) {
+        var btn = e.target.closest && e.target.closest('[data-sidebar-collapse-toggle]');
+        var shell = btn && btn.closest('.docs-shell');
+        if (!shell) return;
+        var collapsed = shell.getAttribute('data-sidebar-collapsed') !== 'true';
+        shell.setAttribute('data-sidebar-collapsed', collapsed ? 'true' : 'false');
+        try { localStorage.setItem(COLLAPSE_KEY, collapsed ? 'collapsed' : 'expanded'); } catch (e) {}
+    }
+
+    function restoreCollapse(root) {
+        var saved = null;
+        try { saved = localStorage.getItem(COLLAPSE_KEY); } catch (e) {}
+        if (saved !== 'collapsed' || !root.querySelectorAll) return;
+        var shells = Array.prototype.slice.call(root.querySelectorAll('.docs-shell'));
+        if (root.matches && root.matches('.docs-shell')) shells.unshift(root);
+        shells.forEach(function (shell) { shell.setAttribute('data-sidebar-collapsed', 'true'); });
+    }
+
     function mobileShell(el) {
         return el.closest('.docs-shell, .home-shell') || document.documentElement;
     }
@@ -745,12 +768,16 @@ window.shelldocsChrome = (function () {
     document.addEventListener('click', onTabsClick);
     document.addEventListener('keydown', onTabsKeydown);
     document.addEventListener('click', onMobileNavClick);
+    document.addEventListener('click', onCollapseClick);
     document.addEventListener('keydown', onMobileNavKeydown);
     window.shelldocsOnEnhancedLoad(closeMobileNav);
     watchForReplacedFrames();
+    // The shell is already parsed here; restoring now avoids a flash of the open sidebar.
+    restoreCollapse(document);
 
     function initPage() {
         initToc();
+        restoreCollapse(document);
         restoreTabs(document);
         window.shelldocsIframes.init(document);
     }
diff --git a/tests/ShellDocs.Tests/SidebarCollapseTests.cs b/tests/ShellDocs.Tests/SidebarCollapseTests.cs
new file mode 100644
index 0000000..0346522
--- /dev/null
+++ b/tests/ShellDocs.Tests/SidebarCollapseTests.cs
@@ -0,0 +1,72 @@
+using System.Text.RegularExpressions;
+using ShellDocs.Components;
+using ShellDocs.Components.Chrome;
+using ShellDocs.Components.Layouts;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class SidebarCollapseTests : IDisposable
+{
+    private readonly string _root;
+
+    public SidebarCollapseTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-collapse-" + Guid.NewGuid().ToString("N"));
+        var page = Path.Combine(_root, "docs", "getting-started.md");
+        Directory.CreateDirectory(Path.GetDirectoryName(page)!);
+        File.WriteAllText(page, "---\ntitle: Getting started\n---\n# Getting started\n");
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private ComponentRenderHarness Harness(DocsLayoutVariant layout = DocsLayoutVariant.Sidebar) => new(o =>
+    {
+        o.ContentRoot = _root;
+        o.LayoutVariant = layout;
+    }, "http://localhost/docs/getting-started");
+
+    [Fact]
+    public async Task SidebarCollapse_IsStaticHostFriendly()
+    {
+        var layout = await Harness().RenderAsync<DocsLayout>();
+        Assert.Contains("data-sidebar-collapsed=\"false\"", layout);
+        Assert.Matches("class=\"docs-collapsed-tool\"[^>]*data-sidebar-collapse-toggle[^>]*aria-label=\"Expand sidebar\"", layout);
+        Assert.DoesNotContain("docs-sidebar-collapsed", layout);
+
+        var header = await Harness().RenderAsync<DocsSidebarHeader>();
+        var toggle = Regex.Match(header, "<button[^>]*docs-sidebar-collapse[^>]*>").Value;
+        Assert.Contains("data-sidebar-collapse-toggle", toggle);
+        Assert.DoesNotContain("blazor:onclick", toggle);
+
+        var topNav = await Harness(DocsLayoutVariant.TopNav).RenderAsync<DocsLayout>();
+        Assert.DoesNotContain("docs-collapsed-toolbar", topNav);
+    }
+
+    [Fact]
+    public void ShelldocsJs_TogglesAndRemembersTheCollapse()
+    {
+        var js = File.ReadAllText(FindAsset("shelldocs.js"));
+        Assert.Contains("[data-sidebar-collapse-toggle]", js);
+        Assert.Contains("'shelldocs-sidebar'", js);
+        Assert.Contains("restoreCollapse(added[n])", js);
+    }
+
+    private static string FindAsset(string name)
+    {
+        var testDir = Path.GetDirectoryName(typeof(SidebarCollapseTests).Assembly.Location)!;
+        foreach (var candidate in new[]
+        {
+            Path.Combine(testDir, "wwwroot", "_content", "ShellDocs.Components", name),
+            Path.Combine(testDir, "..", "..", "..", "..", "..", "src", "ShellDocs.Components", "wwwroot", name)
+        })
+        {
+            var full = Path.GetFullPath(candidate);
+            if (File.Exists(full)) return full;
+        }
+        throw new FileNotFoundException(name);
+    }
+}

From 60dc52b680cad46689c08fb8e96714cb6040248c Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Sat, 10 Oct 2026 03:06:57 +0200
Subject: [PATCH 2/5] feat(components): DocsNotFound answers 404; init template
 uses it

Unknown docs pages rendered "Page not found" with status 200, so search engines indexed them. <DocsNotFound /> renders the not-found view and answers 404. The status is set in Response.OnStarting: .NET 10 sends an empty body for a page whose status is already 404 unless the app has a NotFoundPage or status-code re-execution. Path, HomeHref and HomeLabel override the message and the link back, which defaults to where /docs leads. The init template and the example site use it.
---
 .../Components/Pages/DocsPage.razor           | 13 +--
 .../Content/DocsNotFound.razor                | 52 +++++++++++
 .../Content/DocsNotFound.razor.css            | 22 +++++
 src/ShellDocs.Templates/ScaffoldTemplates.cs  |  7 +-
 tests/ShellDocs.Tests/NotFoundTests.cs        | 87 +++++++++++++++++++
 5 files changed, 164 insertions(+), 17 deletions(-)
 create mode 100644 src/ShellDocs.Components/Content/DocsNotFound.razor
 create mode 100644 src/ShellDocs.Components/Content/DocsNotFound.razor.css
 create mode 100644 tests/ShellDocs.Tests/NotFoundTests.cs

diff --git a/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor b/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
index 88dc406..2fbcde8 100644
--- a/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
+++ b/examples/ShellDocs.Preview/Components/Pages/DocsPage.razor
@@ -1,4 +1,3 @@
-@using ShellIcons.Icons
 @page "/docs/{*Path:nonfile}"
 @layout DocsLayout
 @inject NavigationGraph Graph
@@ -12,19 +11,9 @@
 }
 else
 {
-    <div class="doc-not-found">
-        <h1>Page not found</h1>
-        <p>The page <code>@Path</code> doesn't exist yet.</p>
-        <p><a href="/docs/introduction"><ArrowLeft Size="14" style="vertical-align:middle;margin-right:0.35rem" />Back to introduction</a></p>
-    </div>
+    <DocsNotFound />
 }
 
-<style>
-    .doc-not-found { padding: 3rem 0; }
-    .doc-not-found h1 { font-size: 1.5rem; font-weight: 600; }
-    .doc-not-found code { background: var(--muted); padding: 0.125rem 0.375rem; border-radius: 4px; font-family: var(--font-mono); font-size: 0.875em; border: 1px solid var(--border); }
-</style>
-
 @code {
     [Parameter] public string? Path { get; set; }
 
diff --git a/src/ShellDocs.Components/Content/DocsNotFound.razor b/src/ShellDocs.Components/Content/DocsNotFound.razor
new file mode 100644
index 0000000..478c12a
--- /dev/null
+++ b/src/ShellDocs.Components/Content/DocsNotFound.razor
@@ -0,0 +1,52 @@
+@namespace ShellDocs.Components.Content
+@attribute [ShellDocsIgnore]
+@using Microsoft.AspNetCore.Http
+@using ShellIcons.Icons
+@inject NavigationManager Nav
+@inject DocsRedirects Redirects
+@inject NavigationGraph Graph
+
+@* The docs page's "not found" view. It sets HTTP 404 while the response hasn't
+   started (prerender, static SSR), so search engines skip it and `shelldocs build`
+   counts it as a failure; data-shelldocs-not-found marks it for the build too. *@
+<div class="docs-not-found" data-shelldocs-not-found>
+    <h1>Page not found</h1>
+    <p>The page <code>@_path</code> doesn't exist.</p>
+    <p>
+        <a href="@_home"><ArrowLeft Class="docs-not-found-icon" />@HomeLabel</a>
+    </p>
+</div>
+
+@code {
+    [CascadingParameter] public HttpContext? HttpContext { get; set; }
+    // Defaults to the requested URL's path.
+    [Parameter] public string? Path { get; set; }
+    // Defaults to where /docs leads (the first docs page, in the latest version).
+    [Parameter] public string? HomeHref { get; set; }
+    [Parameter] public string HomeLabel { get; set; } = "Back to the docs";
+
+    private string _path = "";
+    private string _home = "/";
+
+    /* Blazor sends an empty body for a page whose status is already 404 unless the app
+       has a NotFoundPage or status-code re-execution, so the status is set as the
+       headers go out, after this view has rendered. */
+    protected override void OnInitialized()
+    {
+        if (HttpContext is { Response.HasStarted: false } http)
+            http.Response.OnStarting(() =>
+            {
+                http.Response.StatusCode = StatusCodes.Status404NotFound;
+                return Task.CompletedTask;
+            });
+    }
+
+    protected override void OnParametersSet()
+    {
+        _path = Path ?? DocsVersionResolver.PathOf(Nav);
+        _home = HomeHref
+            ?? Redirects.Resolve("/docs")?.Url
+            ?? Graph.FirstPageUnder("/docs")?.Url
+            ?? "/";
+    }
+}
diff --git a/src/ShellDocs.Components/Content/DocsNotFound.razor.css b/src/ShellDocs.Components/Content/DocsNotFound.razor.css
new file mode 100644
index 0000000..dd63f45
--- /dev/null
+++ b/src/ShellDocs.Components/Content/DocsNotFound.razor.css
@@ -0,0 +1,22 @@
+.docs-not-found { padding: 3rem 0; }
+.docs-not-found h1 { margin: 0 0 0.75rem; font-size: 1.5rem; font-weight: 600; letter-spacing: -0.015em; }
+.docs-not-found p { margin: 0.5rem 0; color: var(--muted-foreground); }
+.docs-not-found code {
+    padding: 0.125rem 0.375rem;
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    background: var(--muted);
+    color: var(--foreground);
+    font-family: var(--font-mono);
+    font-size: 0.875em;
+}
+.docs-not-found a {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+    color: var(--foreground);
+    font-weight: 500;
+    text-decoration: none;
+}
+.docs-not-found a:hover { text-decoration: underline; text-underline-offset: 3px; }
+.docs-not-found ::deep .docs-not-found-icon { width: 0.875rem; height: 0.875rem; }
diff --git a/src/ShellDocs.Templates/ScaffoldTemplates.cs b/src/ShellDocs.Templates/ScaffoldTemplates.cs
index 8f9c0a5..7412423 100644
--- a/src/ShellDocs.Templates/ScaffoldTemplates.cs
+++ b/src/ShellDocs.Templates/ScaffoldTemplates.cs
@@ -56,11 +56,8 @@ @inject MarkdownRenderer Renderer
         }
         else
         {
-            <div class="doc-not-found">
-                <h1>Page not found</h1>
-                <p>The page <code>@Path</code> doesn't exist yet.</p>
-                <p><a href="/docs/introduction"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:middle;margin-right:0.35rem"><path d="M19 12H5M12 19l-7-7 7-7"/></svg>Back to introduction</a></p>
-            </div>
+            @* Sets HTTP 404, so search engines skip it and `shelldocs build` reports it. *@
+            <DocsNotFound />
         }
 
         @code {
diff --git a/tests/ShellDocs.Tests/NotFoundTests.cs b/tests/ShellDocs.Tests/NotFoundTests.cs
new file mode 100644
index 0000000..d2f16e7
--- /dev/null
+++ b/tests/ShellDocs.Tests/NotFoundTests.cs
@@ -0,0 +1,87 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Rendering;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Http.Features;
+using ShellDocs.Components.Content;
+using ShellDocs.Templates;
+using Xunit;
+
+namespace ShellDocs.Tests;
+
+public class NotFoundTests : IDisposable
+{
+    private readonly string _root;
+
+    public NotFoundTests()
+    {
+        _root = Path.Combine(Path.GetTempPath(), "shelldocs-notfound-" + Guid.NewGuid().ToString("N"));
+        var page = Path.Combine(_root, "docs", "getting-started.md");
+        Directory.CreateDirectory(Path.GetDirectoryName(page)!);
+        File.WriteAllText(page, "---\ntitle: Getting started\n---\n# Getting started\n");
+    }
+
+    public void Dispose()
+    {
+        try { Directory.Delete(_root, recursive: true); } catch { }
+    }
+
+    private ComponentRenderHarness Harness() => new(o => o.ContentRoot = _root, "http://localhost/docs/nope");
+
+    // Cascades an HttpContext the way static SSR / prerendering does.
+    public class WithHttpContext : ComponentBase
+    {
+        [Parameter] public HttpContext? Context { get; set; }
+
+        protected override void BuildRenderTree(RenderTreeBuilder b)
+        {
+            b.OpenComponent<CascadingValue<HttpContext>>(0);
+            b.AddComponentParameter(1, "Value", Context);
+            b.AddComponentParameter(2, "ChildContent", (RenderFragment)(c =>
+            {
+                c.OpenComponent<DocsNotFound>(0);
+                c.CloseComponent();
+            }));
+            b.CloseComponent();
+        }
+    }
+
+    // Runs OnStarting callbacks the way Kestrel does when the headers go out.
+    private sealed class StartingFeature : HttpResponseFeature
+    {
+        private readonly List<(Func<object, Task> Callback, object State)> _callbacks = new();
+        public override void OnStarting(Func<object, Task> callback, object state) => _callbacks.Add((callback, state));
+        public async Task StartAsync() { foreach (var (c, s) in _callbacks) await c(s); }
+    }
+
+    [Fact]
+    public async Task DocsNotFound_Sets404_AsTheHeadersGoOut_AndLinksBackToTheDocs()
+    {
+        var http = new DefaultHttpContext();
+        var feature = new StartingFeature();
+        http.Features.Set<IHttpResponseFeature>(feature);
+        var html = await Harness().RenderAsync<WithHttpContext>(new() { ["Context"] = http });
+
+        Assert.Equal(StatusCodes.Status200OK, http.Response.StatusCode); // Blazor still renders the body
+        await feature.StartAsync();
+        Assert.Equal(StatusCodes.Status404NotFound, http.Response.StatusCode);
+        Assert.Contains("data-shelldocs-not-found", html);
+        Assert.Matches("<code[^>]*>/docs/nope</code>", html);
+        Assert.Matches("<a href=\"/docs/getting-started\"[^>]*>", html);
+    }
+
+    [Fact]
+    public async Task DocsNotFound_WithoutAnHttpContext_StillRenders()
+    {
+        var html = await Harness().RenderAsync<DocsNotFound>(new() { ["Path"] = "/somewhere", ["HomeHref"] = "/start", ["HomeLabel"] = "Start" });
+
+        Assert.Matches("<code[^>]*>/somewhere</code>", html);
+        Assert.Matches("<a href=\"/start\"[^>]*>.*Start</a>", html);
+    }
+
+    [Fact]
+    public void InitTemplate_UsesDocsNotFound()
+    {
+        Assert.Contains("<DocsNotFound />", ScaffoldTemplates.DocsPageRazor);
+        Assert.DoesNotContain("doc-not-found", ScaffoldTemplates.DocsPageRazor);
+    }
+}

From 6d2a65310e92680224af674fe244bf42b846d080 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Sat, 10 Oct 2026 03:06:57 +0200
Subject: [PATCH 3/5] feat(cli): fail the build on not-found pages and write
 404.html

A page that answers 404, or renders <DocsNotFound> with another status, now counts as a prerender failure instead of shipping a "Page not found" page. shelldocs build also requests a URL no site has and, when it renders <DocsNotFound> with a 404, writes it as 404.html for static hosts that serve it (GitHub Pages, Netlify, Cloudflare Pages); --spa-fallback still replaces it with index.html.
---
 src/ShellDocs.CLI/Commands/PrerenderRunner.cs | 36 ++++++++++++++++++-
 tests/ShellDocs.Tests/NotFoundTests.cs        | 12 +++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
index fcb1076..71dc1ec 100644
--- a/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
+++ b/src/ShellDocs.CLI/Commands/PrerenderRunner.cs
@@ -94,11 +94,19 @@ void OnStreamLine(string line)
                     var response = http.GetAsync(url).GetAwaiter().GetResult();
                     if (!response.IsSuccessStatusCode)
                     {
-                        AnsiConsole.MarkupLine($"  [yellow]warn:[/] [cyan]{url}[/] returned [yellow]{(int)response.StatusCode}[/]");
+                        var why = response.StatusCode == HttpStatusCode.NotFound ? "404 (page not found)" : ((int)response.StatusCode).ToString();
+                        AnsiConsole.MarkupLine($"  [yellow]warn:[/] [cyan]{url}[/] returned [yellow]{why}[/]");
                         failed++;
                         continue;
                     }
                     var html = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+                    // A docs page that rendered <DocsNotFound> where the status couldn't be set.
+                    if (IsNotFoundPage(html))
+                    {
+                        AnsiConsole.MarkupLine($"  [yellow]warn:[/] [cyan]{url}[/] rendered [yellow]Page not found[/]");
+                        failed++;
+                        continue;
+                    }
                     var outPath = UrlToFilePath(url, outputDir);
                     Directory.CreateDirectory(Path.GetDirectoryName(outPath)!);
                     File.WriteAllText(outPath, html);
@@ -115,6 +123,7 @@ void OnStreamLine(string line)
 
             var redirects = WriteRedirects(http, outputDir);
             if (redirects > 0) AnsiConsole.MarkupLine($"[dim]redirects:[/] wrote [cyan]{redirects}[/] redirect page(s)");
+            if (WriteNotFoundPage(http, outputDir)) AnsiConsole.MarkupLine("[dim]not found:[/] wrote [cyan]404.html[/]");
             return new Result(failed == 0, rendered, failed);
         }
         finally
@@ -123,6 +132,31 @@ void OnStreamLine(string line)
         }
     }
 
+    internal const string NotFoundMarker = "data-shelldocs-not-found";
+    // A URL no site has, so the docs route renders <DocsNotFound>.
+    internal const string NotFoundProbe = "/docs/__shelldocs-not-found__";
+
+    internal static bool IsNotFoundPage(string html) => html.Contains(NotFoundMarker, StringComparison.Ordinal);
+
+    // Static hosts (GitHub Pages, Netlify, Cloudflare Pages) serve 404.html for unknown
+    // URLs. Written from the site's own not-found view, when its docs route has one.
+    private static bool WriteNotFoundPage(HttpClient http, string outputDir)
+    {
+        try
+        {
+            var response = http.GetAsync(NotFoundProbe).GetAwaiter().GetResult();
+            var html = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
+            if (response.StatusCode != HttpStatusCode.NotFound || !IsNotFoundPage(html)) return false;
+            File.WriteAllText(Path.Combine(outputDir, "404.html"), html);
+            return true;
+        }
+        catch (Exception ex)
+        {
+            AnsiConsole.MarkupLine($"  [yellow]warn:[/] couldn't render the not-found page: {ex.Message}");
+            return false;
+        }
+    }
+
     private record RedirectEntry(string From, string To);
 
     // The app serves its redirect map (DocsRedirectMiddleware); each source URL without
diff --git a/tests/ShellDocs.Tests/NotFoundTests.cs b/tests/ShellDocs.Tests/NotFoundTests.cs
index d2f16e7..5fceda7 100644
--- a/tests/ShellDocs.Tests/NotFoundTests.cs
+++ b/tests/ShellDocs.Tests/NotFoundTests.cs
@@ -1,3 +1,4 @@
+using System.Reflection;
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Rendering;
 using Microsoft.AspNetCore.Http;
@@ -84,4 +85,15 @@ public void InitTemplate_UsesDocsNotFound()
         Assert.Contains("<DocsNotFound />", ScaffoldTemplates.DocsPageRazor);
         Assert.DoesNotContain("doc-not-found", ScaffoldTemplates.DocsPageRazor);
     }
+
+    [Fact]
+    public void Build_TreatsTheNotFoundView_AsAFailure()
+    {
+        var cli = AppDomain.CurrentDomain.GetAssemblies().FirstOrDefault(a => a.GetName().Name == "shelldocs") ?? Assembly.Load("shelldocs");
+        var isNotFound = cli.GetType("ShellDocs.CLI.Commands.PrerenderRunner", throwOnError: true)!
+            .GetMethod("IsNotFoundPage", BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public)!;
+
+        Assert.True((bool)isNotFound.Invoke(null, ["<div class=\"docs-not-found\" data-shelldocs-not-found>"])!);
+        Assert.False((bool)isNotFound.Invoke(null, ["<main>Getting started</main>"])!);
+    }
 }

From 9b7bda82793e6d40690f812ae3811b967b7016e4 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Sat, 10 Oct 2026 03:06:57 +0200
Subject: [PATCH 4/5] docs: static sidebar collapse, 404 status and 404.html

CHANGELOG [Unreleased], README, ARCHITECTURE (chrome table, not-found, build steps) and the installation page.
---
 CHANGELOG.md                                         | 10 ++++++++++
 README.md                                            |  2 +-
 docs/ARCHITECTURE.md                                 | 12 ++++++++----
 .../ShellDocs.Preview/content/docs/installation.md   |  4 ++--
 4 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6bf045..617a103 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 ## [Unreleased]
 
+### Added
+
+- **`<DocsNotFound />`**: the docs page's not-found view, now used by the `init` template. It answers HTTP 404, so search engines skip unknown pages. The status is set as the headers go out, because .NET 10 sends an empty body for a page that is already 404 unless the app has a `NotFoundPage` or status-code re-execution. `Path`, `HomeHref` and `HomeLabel` override the message and the link back (which defaults to where `/docs` leads). Existing sites replace their `else` branch in `DocsPage.razor` with `<DocsNotFound />`.
+- **`shelldocs build` writes `404.html`** from the site's own not-found view, for static hosts that serve it for unknown URLs (GitHub Pages, Netlify, Cloudflare Pages). `--spa-fallback` still replaces it with `index.html`.
+
+### Changed
+
+- **Desktop sidebar collapse works without a Blazor runtime.** The collapse and expand buttons are `[data-sidebar-collapse-toggle]` buttons handled by `shelldocs.js`, which flips `[data-sidebar-collapsed]` on the page shell and remembers the choice in `localStorage` across pages. The page shell no longer gets a `docs-sidebar-collapsed` class; style `[data-sidebar-collapsed="true"]` instead. `SidebarCollapseState` is still registered but no longer used.
+- **`shelldocs build` fails on a page that renders as not found**, whether it answered 404 or rendered `<DocsNotFound>` with another status.
+
 ## [0.1.13-alpha] — 2026-10-10
 
 Code variants for cross-platform libraries: one preview with code tabs per platform (MAUI and Avalonia XAML, say), a page switch that picks the platform site-wide, captions, and live iframe previews. Also fixes one-line component bodies being wrapped in `<p>`.
diff --git a/README.md b/README.md
index 9b8fd8a..5010d7d 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ Already have a Blazor project? Run `shelldocs init --attach` inside it: it adds
   ```
   Your components win name collisions with ShellDocs' built-ins, which stay available as `<DocsCard>`, `<DocsCallout>`, `<DocsTabs>`, and so on.
 - **Content primitives.** `Callout`, `Card` / `CardGrid` / `LinkCard`, `Steps`, `FileTree`, `Tabs`, `CodeGroup`, `TypeTable` / `AutoTypeTable`, `ComponentPreview`, `DemoPreview`.
-- **Static export.** `shelldocs build` prerenders every page to static HTML for GitHub Pages, Cloudflare Pages, Netlify or S3. Optional flags rewrite `<base href>` (`--base-href`), add a SPA `404.html` (`--spa-fallback`), and write sitemap / robots / `og:` meta (`--site-url`). Navigation, sidebar sections, the mobile menu, selectors, tabs, preview toolbars, the TOC and code copy work there through `shelldocs.js`. So does the theme toggle. Search, desktop sidebar collapse and stateful demos need a running Blazor app.
+- **Static export.** `shelldocs build` prerenders every page to static HTML for GitHub Pages, Cloudflare Pages, Netlify or S3. Optional flags rewrite `<base href>` (`--base-href`), add a SPA `404.html` (`--spa-fallback`), and write sitemap / robots / `og:` meta (`--site-url`). Navigation, sidebar sections and collapse, the mobile menu, selectors, tabs, preview toolbars, the TOC, code copy and the theme toggle work there through `shelldocs.js`. Only search and stateful demos need a running Blazor app. Unknown pages answer 404 (`<DocsNotFound />` in the docs page) and `build` writes the same view as `404.html`.
 
 ## Versioned docs
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 4fc4f7a..25e770c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -209,10 +209,13 @@ Chrome that must work without a Blazor runtime follows one contract:
 | Tabs, CodeGroup, preview code tabs, page switch | `[data-tabs]`, `[data-tab-target]`, `[data-tab-panel]` | switch on click / arrows; `[data-tabs-sync]` groups switch together and persist in `localStorage`; a `[data-tabs-missing]` group without the chosen value shows its `[data-tab-missing]` note; with nothing saved yet, groups follow a `[data-tabs-switch]` for their key |
 | Iframe previews | `[data-iframe-preview][data-src][data-lazy]` | sets the iframe's `src` (plus `?theme=`) when visible (IntersectionObserver), on `[data-iframe-run]` or at once; posts `{ type: "shelldocs-theme", theme }` to loaded frames on theme change |
 | Mobile nav | page shell `[data-mobile-open]` | hamburger toggles; backdrop, Escape, link or navigation closes; page scroll locked on `<html>` |
+| Sidebar collapse | page shell `[data-sidebar-collapsed]`, `[data-sidebar-collapse-toggle]` | toggles collapse; remembered in `localStorage` and restored as soon as `shelldocs.js` runs, so the sidebar doesn't flash open |
 | TOC | `[data-toc-list][data-toc-ids]` | IntersectionObserver scroll-spy, re-attached on `enhancedload` |
 | Theme | `<html class="dark">`, `[data-theme-toggle]` | inline head script applies the saved / system theme; the toggle flips the class and CSS picks its icon; a `MutationObserver` saves any change (including another library's toggle) and pushes it to `ThemeState`; re-applied after enhanced navigation |
 
-Still Blazor-only: search, the desktop sidebar-collapse button.
+Still Blazor-only: search.
+
+**Not found.** `<DocsNotFound />` is the docs page's not-found view. It answers 404 by setting the status in `Response.OnStarting`: .NET 10 sends an empty body for a page whose status is already 404 unless the app has a `NotFoundPage` or status-code re-execution, so the status has to change only as the headers go out. It carries `data-shelldocs-not-found`, which `shelldocs build` checks for.
 
 `enhancedload` is a Blazor event (`Blazor.addEventListener`), not a DOM event; `shelldocsOnEnhancedLoad(fn)` attaches once `blazor.web.js` has run.
 
@@ -240,10 +243,11 @@ One neutral, shadcn-shaped palette of CSS variables in `ShellDocs.Tokens/tokens.
 
 1. `dotnet publish -c Release` into `obj/shelldocs-publish`, then copies in any `content/` file publish left out (a csproj that copies `meta.json` but not `.md`).
 2. Builds the navigation graph and collects every URL (visible and hidden) plus `/`.
-3. `PrerenderRunner` starts the published app on a free port, requests each URL and writes `<output>/<path>/index.html`.
+3. `PrerenderRunner` starts the published app on a free port, requests each URL and writes `<output>/<path>/index.html`. A URL that answers 404, or renders `<DocsNotFound>`, fails the build.
 4. Reads the app's redirect map and writes a redirect page for each source URL without a prerendered page (meta refresh plus `location.replace`, relative to `<base href>`).
-5. Merges the published `wwwroot/` into the output without overwriting prerendered HTML.
-6. Optionally rewrites `<base href>` in every HTML file, copies `index.html` to `404.html`, and with `--site-url` writes `sitemap.xml`, `robots.txt` and `og:*` meta.
+5. Requests `/docs/__shelldocs-not-found__` and, if it renders `<DocsNotFound>` with a 404, writes it as `404.html`.
+6. Merges the published `wwwroot/` into the output without overwriting prerendered HTML.
+7. Optionally rewrites `<base href>` in every HTML file, copies `index.html` to `404.html` (replacing the not-found page), and with `--site-url` writes `sitemap.xml`, `robots.txt` and `og:*` meta.
 
 ---
 
diff --git a/examples/ShellDocs.Preview/content/docs/installation.md b/examples/ShellDocs.Preview/content/docs/installation.md
index f25c3e7..ffcf76d 100644
--- a/examples/ShellDocs.Preview/content/docs/installation.md
+++ b/examples/ShellDocs.Preview/content/docs/installation.md
@@ -52,9 +52,9 @@ shelldocs build
 `shelldocs build` prerenders every page to static HTML in `publish/` (change it with `--output`). Deploy it to GitHub Pages, Cloudflare Pages, Netlify or S3. Useful flags:
 
 - `--base-href /my-repo/` rewrites `<base href>` for sites served from a subpath.
-- `--spa-fallback` copies `index.html` to `404.html`.
+- `--spa-fallback` copies `index.html` to `404.html`. Without it, `404.html` is the site's own not-found page, which GitHub Pages, Netlify and Cloudflare Pages serve for unknown URLs.
 - `--site-url https://docs.example.com` emits `sitemap.xml`, `robots.txt` and `og:` meta tags.
 
-In the static output, navigation, sidebar sections, the mobile menu, the version and package selectors, tabs, preview tabs and menus, the table of contents, the theme toggle and code copy all work through `shelldocs.js`. Search, the desktop sidebar-collapse button and stateful demo components still need a running Blazor Server app (interactive server rendering).
+In the static output, navigation, sidebar sections and collapse, the mobile menu, the version and package selectors, tabs, preview tabs and menus, the table of contents, the theme toggle and code copy all work through `shelldocs.js`. Search and stateful demo components still need a running Blazor Server app (interactive server rendering).
 
 URLs that aren't pages (folders, version roots, unversioned URLs that moved into a version) become redirect pages in the static output, the same redirects the running app answers.

From fe6841c53fb82696d142168c0ff757bdd8e42d44 Mon Sep 17 00:00:00 2001
From: Shewart <shewartshepherd23@gmail.com>
Date: Sat, 10 Oct 2026 03:06:58 +0200
Subject: [PATCH 5/5] chore: bump to 0.1.14-alpha, changelog

Cuts the Unreleased section as 0.1.14-alpha and records the release in the ROADMAP's hardening list.
---
 CHANGELOG.md          | 7 ++++++-
 Directory.Build.props | 2 +-
 docs/ROADMAP.md       | 3 ++-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 617a103..d9c827e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@ All notable changes to ShellDocs land here. Format follows [Keep a Changelog](ht
 
 ## [Unreleased]
 
+## [0.1.14-alpha] — 2026-10-10
+
+Static sites get the last piece of interactive chrome apart from search, the desktop sidebar collapse, and unknown pages finally answer 404, with a matching `404.html` in static exports.
+
 ### Added
 
 - **`<DocsNotFound />`**: the docs page's not-found view, now used by the `init` template. It answers HTTP 404, so search engines skip unknown pages. The status is set as the headers go out, because .NET 10 sends an empty body for a page that is already 404 unless the app has a `NotFoundPage` or status-code re-execution. `Path`, `HomeHref` and `HomeLabel` override the message and the link back (which defaults to where `/docs` leads). Existing sites replace their `else` branch in `DocsPage.razor` with `<DocsNotFound />`.
@@ -410,7 +414,8 @@ Published to NuGet:
 - `<TypeTable>` is hand-authored today; XML-doc auto-generation ships in `ShellDocs.Xml` (Phase 4)
 - No `<DocsBreadcrumb>` opt-out — currently hides when the trail has ≤ 1 node, otherwise always renders
 
-[Unreleased]: https://github.com/shellui-dev/shelldocs/compare/v0.1.13-alpha...HEAD
+[Unreleased]: https://github.com/shellui-dev/shelldocs/compare/v0.1.14-alpha...HEAD
+[0.1.14-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.14-alpha
 [0.1.13-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.13-alpha
 [0.1.12-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.12-alpha
 [0.1.11-alpha]: https://github.com/shellui-dev/shelldocs/releases/tag/v0.1.11-alpha
diff --git a/Directory.Build.props b/Directory.Build.props
index f21553d..da075e8 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -17,7 +17,7 @@
 
   <!-- Package metadata (applies to any project with IsPackable=true) -->
   <PropertyGroup>
-    <Version>0.1.13-alpha</Version>
+    <Version>0.1.14-alpha</Version>
     <Authors>ShellUI</Authors>
     <Company>ShellUI</Company>
     <Copyright>Copyright © 2026 ShellUI</Copyright>
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 45fdc6c..3c25fe2 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -209,7 +209,7 @@ Ships to `ShellDocs.Components` + `ShellDocs.Templates` + `ShellDocs.CLI` + `She
 **Authoring fix (`ShellDocs.Markdown`)**
 - `SlotExtractor.ReplaceComponentTags` no longer `.Trim()`s the raw child content of inline component tags. The Trim was stripping the first line's indent and defeating `SlotRenderer.Dedent` — Markdig then interpreted the remaining 4-space-indented lines as an indented code block. Symptom was the same "literal `<pre>` around placeholder divs" bug that had already been fixed for `razor:preview` fences; the inline-tag code path was still hitting it.
 
-### ✅ Hardening releases (`0.1.3`–`0.1.13-alpha`) — shipped
+### ✅ Hardening releases (`0.1.3`–`0.1.14-alpha`) — shipped
 Driven by building the ShellUI docs on ShellDocs. Highlights (details in the CHANGELOG):
 
 - `feat/build-static-prerender` (0.1.5) — `shelldocs build` prerenders every URL into a static site.
@@ -220,6 +220,7 @@ Driven by building the ShellUI docs on ShellDocs. Highlights (details in the CHA
 - `fix/sidebar-index-pages` (0.1.11) — index pages as sidebar section links, `scroll` preview layout and phone-width previews, scrolling tables.
 - `fix/fence-scanner-inline-attrs` (0.1.12) — CommonMark fences (any length, tildes), inline and named-slot tags read by the Razor tag scanner so `>` in a quoted value is safe, `<TypeTable>` rows that share a name.
 - `feat/preview-code-variants` (0.1.13) — code tabs on previews with sync and a missing-tab note, page switch (`AddSyncSwitch`), captions, `<IframePreview>`, XAML highlighting; one-line component bodies stay inline.
+- `fix/not-found-and-sidebar-collapse` (0.1.14) — `<DocsNotFound>` answers 404, `build` fails on not-found pages and writes `404.html`, desktop sidebar collapse in `shelldocs.js`.
 - `fix/preview-fidelity`, `feat/generics-redirects-page-title` (0.1.10) — `not-prose` previews, Razor child content, stretch layout, generic components in markdown, redirects (middleware + static pages), `RenderPageTitle`, theme sync and a static-host `ThemeToggle`.
 
 ### `feat/animation-polish`