docs: shelldocs preview, and --base-href fixing links

New CLI page for shelldocs preview, linked from build, deployment, the quick start and the CLI package page. The build and deployment pages say --base-href now puts the subpath in front of root-relative links.

Author: Shewart

README.md

@@ -59,13 +59,13 @@ content/
     authoring/          frontmatter, code fences, razor:preview, inline tags, navigation
     components/         one page per content primitive
     guides/             component libraries, versioning, redirects, search, llms.txt, not-found, deployment
-    cli/                init, add, dev, build
+    cli/                init, add, dev, build, preview
     theming.md
     packages/           one overview per NuGet package
 wwwroot/
   favicon.svg, favicon.png, apple-touch-icon.png
   brand/mark.svg        the logo, read into LogoSvg in Program.cs
-  demos/                static pages shown with <IframePreview>
+  demos/                static pages shown with <IframePreview> (theme frame, colour presets)
   cli-replay.js         the terminal replay on the home page
   copy-button.js        copy buttons marked with data-copy
 Llms/

content/docs/cli/build.md

@@ -59,7 +59,7 @@ Rewrites the base href, replaces `404.html` with the home page, and adds the sit
 </Step>
 </Steps>
 
-The project stays a normal Blazor Web App. Nothing about it changes for the export.
+The project stays a normal Blazor Web App. Nothing about it changes for the export. To check the result before deploying, run [`shelldocs preview`](/docs/cli/preview).
 
 ## Custom pages
 
@@ -83,12 +83,14 @@ Without the flag none of these are written, so a local build never produces a si
 
 ### `--base-href`
 
-For a site served from a subpath. Rewrites the `base` tag in every HTML file so assets resolve under the subpath. Include the leading and trailing slash.
+For a site served from a subpath. Rewrites the `base` tag in every HTML file so assets resolve under the subpath, and puts the subpath in front of every root-relative `href`, `src` and `data-src`, so links in the sidebar, header, breadcrumb, page content and prev/next stay inside the site. Include the leading and trailing slash.
 
 ```bash
 shelldocs build --base-href /my-repo/
 ```
 
+Before `0.1.18-alpha` only the `base` tag changed, and root-relative links such as `/docs/introduction` led out of the subpath. [`shelldocs preview`](/docs/cli/preview) serves the export under the subpath, to check it.
+
 ### `--spa-fallback`
 
 Replaces `404.html` with a copy of the root `index.html`, so a host that serves `404.html` for unknown URLs shows the home page instead of the not-found page.
@@ -125,5 +127,6 @@ Search, the sidebar, tabs and the rest of the chrome work in the export: `shelld
 
 <CardGrid Columns="2">
 <LinkCard Title="Deployment" Description="GitHub Pages workflow, custom domains, and .NET hosting." Href="/docs/guides/deployment" />
+<LinkCard Title="shelldocs preview" Description="Serve the export locally, as a static host would." Href="/docs/cli/preview" />
 <LinkCard Title="shelldocs dev" Description="Iterate locally before you publish." Href="/docs/cli/dev" />
 </CardGrid>

content/docs/cli/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "CLI",
-  "pages": ["init", "add", "dev", "build"]
+  "pages": ["init", "add", "dev", "build", "preview"]
 }

content/docs/cli/preview.md

@@ -0,0 +1,73 @@
+---
+title: shelldocs preview
+description: Serve the output of shelldocs build locally, the way a static host would, to check an export before deploying it.
+order: 5
+---
+
+# `shelldocs preview`
+
+`shelldocs preview` serves the static site that [`shelldocs build`](/docs/cli/build) wrote, the way GitHub Pages, Netlify and Cloudflare Pages serve it. Use it to check an export before you deploy: links, the not-found page, search, a site built for a subpath.
+
+## Synopsis
+
+```bash
+shelldocs preview [--dir <dir>] [--output <path>] [--port <n>] [--base-href <path>]
+```
+
+## Default use
+
+Build, then preview, from the docs project folder:
+
+```bash
+shelldocs build
+shelldocs preview
+```
+
+The export in `./publish` is served at `http://localhost:5050`. Press `Ctrl+C` to stop.
+
+## How it serves
+
+<TypeTable>
+<TypeRow Name="A file" Type="200" Description="Served as it is, with a content type from its extension." />
+<TypeRow Name="A folder" Type="200" Description="Its index.html. Every page of an export is a folder with an index.html." />
+<TypeRow Name="{path}.html" Type="200" Description="Used when there is no file or folder of that name." />
+<TypeRow Name="Anything else" Type="404" Description="The export's 404.html, with a 404 status, as most static hosts do." />
+</TypeTable>
+
+Nothing is cached, so after a rebuild a reload shows the new output. Requests can't reach files outside the export.
+
+## Sites built for a subpath
+
+An export built with `--base-href /my-repo/` is served under that path. `shelldocs preview` reads the base from the export's `index.html`, so it needs no flag:
+
+```bash
+shelldocs build --base-href /my-repo/
+shelldocs preview
+```
+
+The site is at `http://localhost:5050/my-repo/`, and `/` redirects there. Pass `--base-href` to serve under another path than the one the build wrote.
+
+## Options
+
+<TypeTable>
+<TypeRow Name="--dir" Type="string" Default="current folder" Description="Project folder. --output is relative to it." />
+<TypeRow Name="--output" Type="string" Default="publish" Description="The static site to serve, as passed to shelldocs build." />
+<TypeRow Name="--port" Type="int" Default="5050" Description="Port to listen on." />
+<TypeRow Name="--base-href" Type="string?" Default="the export's base href" Description="Path to serve the site under." />
+</TypeTable>
+
+## Exit codes
+
+<TypeTable>
+<TypeRow Name="0" Type="ok" Description="Stopped with Ctrl+C." />
+<TypeRow Name="1" Type="error" Description="No index.html in the output folder. Run shelldocs build first, or point --output at its folder." />
+</TypeTable>
+
+The command needs the ASP.NET Core runtime, which any machine that builds a Blazor site already has. It was added in `0.1.18-alpha`, replacing an unfinished `preview <name>` placeholder.
+
+## See also
+
+<CardGrid Columns="2">
+<LinkCard Title="shelldocs build" Description="Write the static site this command serves." Href="/docs/cli/build" />
+<LinkCard Title="Deployment" Description="What works on a static host, and how to publish." Href="/docs/guides/deployment" />
+</CardGrid>

content/docs/getting-started/installation.md

@@ -71,7 +71,7 @@ dotnet add package ShellDocs.Tokens --prerelease
 ## The package family
 
 <TypeTable>
-<TypeRow Name="ShellDocs.CLI" Type="global tool" Description="shelldocs init, add, dev, build. Installed once, works from any directory." />
+<TypeRow Name="ShellDocs.CLI" Type="global tool" Description="shelldocs init, add, dev, build, preview. Installed once, works from any directory." />
 <TypeRow Name="ShellDocs.Components" Type="RCL" Description="The chrome (layout, sidebar, search, header) and content primitives (Callout, Card, Steps, CodeGroup, TypeTable, more)." />
 <TypeRow Name="ShellDocs.Tokens" Type="RCL" Description="Shared CSS variables. shadcn-compatible names for interop with ShellUI and other design systems." />
 <TypeRow Name="ShellDocs.Core" Type="library (transitive)" Description="Navigation graph, search index, markdown plain-text extraction." />

content/docs/getting-started/quick-start.md

@@ -77,7 +77,7 @@ Other templates:
 shelldocs build --output publish
 ```
 
-Prerenders every page into `publish/` as static files. Upload the folder to any static host. See [Deployment](/docs/guides/deployment) for a GitHub Pages workflow and for what needs a server instead.
+Prerenders every page into `publish/` as static files. Check them with `shelldocs preview`, which serves the folder at `http://localhost:5050` the way a static host would, then upload the folder to any static host. See [Deployment](/docs/guides/deployment) for a GitHub Pages workflow and for what needs a server instead.
 </Step>
 </Steps>
 

content/docs/guides/deployment.md

@@ -58,6 +58,12 @@ The output goes to `./publish`. Every flag is covered in [shelldocs build](/docs
 - `--site-url` adds `sitemap.xml`, `robots.txt` and social-preview meta tags.
 - `--base-href` is needed only when the site is served from a subpath, such as a GitHub project page at `/my-repo/`.
 
+Before uploading, check the export with [`shelldocs preview`](/docs/cli/preview). It serves `publish` at `http://localhost:5050` the way a static host does, including `404.html` for unknown URLs and the subpath of a `--base-href` build.
+
+```bash
+shelldocs preview
+```
+
 ## GitHub Pages
 
 This workflow builds on every push to `main` and can be run by hand.
@@ -141,6 +147,8 @@ For a site served at `https://your-org.github.io/my-repo/`, drop the `CNAME` ste
 shelldocs build --base-href /my-repo/
 ```
 
+The build puts `/my-repo/` in front of every root-relative link, and `shelldocs preview` serves the export at `http://localhost:5050/my-repo/` to check it.
+
 ## Other static hosts
 
 Any host that serves a folder works: point it at `publish`. Many hosts' own build environments don't include the .NET SDK, so the dependable setup is to run `shelldocs build` in CI and upload the output, as the workflow above does.
@@ -169,6 +177,7 @@ Any platform that runs ASP.NET Core works: a container, a virtual machine, or a
 
 <CardGrid Columns="2">
 <LinkCard Title="shelldocs build" Description="Every flag and what the build does." Href="/docs/cli/build" />
+<LinkCard Title="shelldocs preview" Description="Check the export locally before deploying." Href="/docs/cli/preview" />
 <LinkCard Title="Redirects" Description="How redirects are written into a static export." Href="/docs/guides/redirects" />
 <LinkCard Title="Search" Description="How search works without a server." Href="/docs/guides/search" />
 <LinkCard Title="Not-found page" Description="DocsNotFound and the 404.html the build writes." Href="/docs/guides/not-found" />

content/docs/introduction.md

@@ -64,7 +64,7 @@ The whole thing renders : Callout with icon and variant styling, live Button com
 ## The three packages you'll touch most
 
 <TypeTable>
-<TypeRow Name="ShellDocs.CLI" Type="global tool" Description="shelldocs init, add, dev, build. Installed once, works from any directory." />
+<TypeRow Name="ShellDocs.CLI" Type="global tool" Description="shelldocs init, add, dev, build, preview. Installed once, works from any directory." />
 <TypeRow Name="ShellDocs.Components" Type="Razor Class Library" Description="The chrome (layout, sidebar, search, header) and content primitives (Callout, Card, Steps, CodeGroup, TypeTable, more)." />
 <TypeRow Name="ShellDocs.Tokens" Type="Razor Class Library" Description="Shared CSS variables : palette + spacing scale. shadcn-compatible names for interop with ShellUI and other design systems." />
 </TypeTable>

content/docs/packages/cli.md

@@ -1,6 +1,6 @@
 ---
 title: ShellDocs.CLI
-description: The command-line tool. shelldocs init, add, dev, build. The daily-driver surface for scaffolding, authoring, and shipping.
+description: The command-line tool. shelldocs init, add, dev, build, preview. The daily-driver surface for scaffolding, authoring, and shipping.
 order: 3
 ---
 
@@ -24,13 +24,14 @@ The `--prerelease` flag is required while ShellDocs is on `0.x.y-alpha` versions
 dotnet tool update -g ShellDocs.CLI --prerelease
 ```
 
-## The four commands
+## The five commands
 
 <TypeTable>
 <TypeRow Name="init" Type="command" Description="Scaffold a fresh ShellDocs site OR augment an existing Blazor project. Two modes: create (default) and attach (--attach)." />
 <TypeRow Name="add" Type="command" Description="Scaffold a starter .md page from a template (component / guide / page) into content/." />
 <TypeRow Name="dev" Type="command" Description="Start the dev server with hot-reload on .md / .razor / .cs changes." />
 <TypeRow Name="build" Type="command" Description="Export a static site: prerenders every page, writes redirects, optional sitemap and social meta tags." />
+<TypeRow Name="preview" Type="command" Description="Serve the exported site locally the way a static host would, to check it before deploying." />
 </TypeTable>
 
 ## `shelldocs init`
@@ -88,6 +89,14 @@ shelldocs build --output publish --base-href "/my-repo/"   # for GH Pages subpat
 
 Publishes the project, starts it locally, saves every page as static HTML, writes redirect pages, a `404.html`, the search index and the [llms.txt files](/docs/guides/llms-txt), and copies the assets. `--site-url` adds a sitemap, a robots file and social meta tags; `--base-href` handles subpath hosting; `--spa-fallback` replaces `404.html` with the home page. See [shelldocs build](/docs/cli/build).
 
+## `shelldocs preview`
+
+```bash
+shelldocs preview                 # serve ./publish at http://localhost:5050
+```
+
+Serves the export the way a static host does: folders serve their `index.html`, unknown URLs get `404.html`, and a site built with `--base-href` is served under that path. See [shelldocs preview](/docs/cli/preview).
+
 ## Version discipline
 
 `shelldocs init` scaffolds package references at the CLI's own version, read from its assembly. A project scaffolded with CLI `0.1.18-alpha` references the `0.1.18-alpha` packages. In CI, pin the tool to the same version your project references.