docs: ShellDocs 0.1.18 (colour presets, shelldocs preview)

Llms/agent-rules.md

@@ -6,6 +6,6 @@ Read these before building or changing a ShellDocs site.
 2. **Pages are Markdown files** in `content/docs/`, with `title` and `description` frontmatter. Each folder's `meta.json` sets the sidebar order and must list every page. `shelldocs add page|guide|component <name>` scaffolds one. New pages and `meta.json` edits need a restart of the running site.
 3. **Use ShellDocs' components in Markdown; don't write HTML look-alikes.** `<Callout>`, `<Tabs>` / `<Tab>`, `<Steps>` / `<Step>`, `<CardGrid>` / `<Card>` / `<LinkCard>`, `<CodeGroup>`, `<FileTree>`, `<TypeTable>` / `<TypeRow>` and `<AutoTypeTable>`. When a site's own library has a component of the same name, the `Docs` prefix (`<DocsCallout>`) still reaches the built-in.
 4. **Live examples:** a ```` ```razor:preview ```` fence, `<ComponentPreview>`, or `<DemoPreview Component="X" />` for a `.razor` file under `DemoSourceRoot`. A `razor:preview` body is Razor, not Markdown: use `<code>` and `<strong>`, not backticks and `**`. Components used in Markdown must be registered with `RegisterComponent<T>()` or `RegisterComponentsFromAssembly<T>()`.
-5. **Attribute values on tags in Markdown are plain text.** They aren't Markdown and HTML entities aren't decoded. There is no escape for the quote character, so switch between single and double quotes.
+5. **Attribute values on tags in Markdown are plain text, not Markdown.** HTML entities in them are decoded (`&amp;`, `&quot;`). For a value that holds double quotes, wrap it in single quotes or write `&quot;`.
 6. **Configuration lives in `AddShellDocs(o => ...)` in `Program.cs`:** site details, navigation, packages, versions, redirects, previews and `EnableLlmsTxt`.
 7. **Static sites come from `shelldocs build`.** Don't edit the `publish/` output by hand, and don't add `--spa-fallback` unless the host needs it: it replaces the not-found page with the home page.

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/
@@ -78,7 +78,7 @@ Components/
 
 ## Framework version
 
-The site references `ShellDocs.* 0.1.17-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` together.
+The site references `ShellDocs.* 0.1.18-alpha`. On a new release, bump the four package versions in `ShellDocs.Site.csproj` together.
 
 ## Deploying
 

ShellDocs.Site.csproj

@@ -19,10 +19,10 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
-    <PackageReference Include="ShellDocs.Core"       Version="0.1.17-alpha" />
-    <PackageReference Include="ShellDocs.Markdown"   Version="0.1.17-alpha" />
-    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.17-alpha" />
+    <PackageReference Include="ShellDocs.Components" Version="0.1.18-alpha" />
+    <PackageReference Include="ShellDocs.Core"       Version="0.1.18-alpha" />
+    <PackageReference Include="ShellDocs.Markdown"   Version="0.1.18-alpha" />
+    <PackageReference Include="ShellDocs.Tokens"     Version="0.1.18-alpha" />
   </ItemGroup>
 
   <ItemGroup>

content/docs/authoring/component-tags.md

@@ -78,11 +78,17 @@ A quoted value can hold anything except its own quote character. Angle brackets,
 Three things to know:
 
 <TypeTable>
-<TypeRow Name="Quotes" Type="choose" Description="There is no escape for a quote inside a value. Wrap the value in single quotes when it contains double quotes, and the other way round." />
+<TypeRow Name="Quotes" Type="choose" Description="Wrap the value in single quotes when it contains double quotes, and the other way round. Or write the quote as an entity." />
 <TypeRow Name="Markdown" Type="literal" Description="Attribute text is not markdown. Backticks and asterisks show up as typed. Put formatted text in the tag body." />
-<TypeRow Name="HTML entities" Type="literal" Description="Entities are not decoded. Write the character itself." />
+<TypeRow Name="HTML entities" Type="decoded" Description="Entities are decoded, as Razor does. Before 0.1.18-alpha they showed literally." />
 </TypeTable>
 
+```markdown
+<Callout Title="Tom &amp; Jerry say &quot;hi&quot;" />
+```
+
+The title reads: Tom & Jerry say "hi". Entities inside a code span in the value, `@` expressions and directive attributes such as `@onclick` stay as written.
+
 A tag whose quote is never closed, or that runs across a blank line, is treated as plain text rather than a component.
 
 ## Code spans stay code

content/docs/authoring/fenced-code.md

@@ -109,7 +109,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>

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/init.md

@@ -44,7 +44,7 @@ The single-page router that serves every `/docs/**` URL from the `.md` files und
 Deletes `Counter.razor`, `Weather.razor`, `NavMenu.razor`, `MainLayout.razor.css`, `Home.razor.css`. Rewrites `MainLayout.razor` as a bare pass-through and replaces `Home.razor` with the ShellDocs welcome page.
 </Step>
 <Step Title="Patches `Program.cs`">
-Adds `using ShellDocs.Components;`, `builder.WebHost.UseStaticWebAssets();`, and `builder.Services.AddShellDocs(...)` : anchoring on the exact template shape produced by `dotnet new blazor`. The `AddShellDocs` call turns on [llms.txt for AI agents](/docs/guides/llms-txt) with `o.EnableLlmsTxt(...)`, its options commented out.
+Adds `using ShellDocs.Components;`, `builder.WebHost.UseStaticWebAssets();`, and `builder.Services.AddShellDocs(...)` : anchoring on the exact template shape produced by `dotnet new blazor`. The `AddShellDocs` call turns on [llms.txt for AI agents](/docs/guides/llms-txt) with `o.EnableLlmsTxt(...)`, its options commented out, and sets the [colour preset](/docs/theming#colour-presets) from `--theme`.
 </Step>
 <Step Title="Patches `Components/App.razor`">
 Adds the `_content/ShellDocs.Tokens/tokens.css` and component CSS links, the theme-bootstrap script, and `shelldocs.js` + Shiki loader. Also switches `<Routes />` to `<Routes @rendermode="InteractiveServer" />` so interactive components (theme toggle, search, tabs) come alive.
@@ -103,7 +103,7 @@ A per-project setup guide with copy-paste snippets for the exact `AddShellDocs`,
 <TypeRow Name="--dir" Type="string" Default="cwd" Description="Working directory. With --attach, the project directory to augment." />
 <TypeRow Name="--attach" Type="bool" Default="false" Description="Attach mode : augment an existing Blazor project instead of creating one." />
 <TypeRow Name="--yes" Type="bool" Default="false" Description="Non-interactive : skip the GitHub-repo prompt, take defaults everywhere." />
-<TypeRow Name="--theme" Type="string" Default="shadcn" Description="Accepted values are shadcn, fuma and nextra. Has no effect in this release: every site gets the same tokens." />
+<TypeRow Name="--theme" Type="string" Default="graphite" Description="Colour preset: graphite, harbor, lagoon, forest, savanna, ember or jacaranda. Writes o.Theme = ShellDocsTheme.{Preset} into Program.cs; graphite, the default, leaves it as a commented-out example. See Theming." />
 </TypeTable>
 
 ## Exit codes

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/components/card.md

@@ -42,8 +42,6 @@ The same attribute works on a `Card` written straight into the page:
 
 <Card Title="Composable" IconSvg="<svg viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2'><rect x='3' y='3' width='7' height='7' rx='1'/><rect x='14' y='3' width='7' height='7' rx='1'/><rect x='3' y='14' width='7' height='7' rx='1'/><rect x='14' y='14' width='7' height='7' rx='1'/></svg>" Description="An inline card with an icon." />
 
-Write the markup itself, not HTML entities : attribute values are not decoded.
-
 ## With child content
 
 Use `ChildContent` for anything richer than a description : lists, a code block, another primitive.

content/docs/components/code-group.md

@@ -21,7 +21,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>
@@ -41,7 +41,7 @@ dotnet add package ShellDocs.Components --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>
@@ -63,7 +63,7 @@ dotnet add package ShellDocs.Core --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Core" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Core" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>
@@ -80,7 +80,7 @@ dotnet add package ShellDocs.Markdown --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Markdown" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Markdown" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>

content/docs/getting-started/configuration.md

@@ -1,6 +1,6 @@
 ---
 title: Configuration
-description: Every option on ShellDocsOptions. Site details, layout, navigation, packages, versions, redirects, branding and component registration.
+description: Every option on ShellDocsOptions. Site details, layout, navigation, packages, versions, redirects, branding, colour preset and component registration.
 order: 4
 ---
 
@@ -174,9 +174,17 @@ o.EnableLlmsTxt(l =>
 
 The options and the files are covered in [AI agents (llms.txt)](/docs/guides/llms-txt).
 
-## Options that do nothing yet
+## Colour preset
 
-`Theme` and the `--theme` flag of `shelldocs init` are accepted but have no effect in this release. Every site uses the same tokens; restyle through [Theming](/docs/theming).
+<TypeTable>
+<TypeRow Name="Theme" Type="ShellDocsTheme" Default="Graphite" Description="The palette: Graphite (neutral), Harbor, Lagoon, Forest, Savanna, Ember or Jacaranda. Covers light and dark mode; your own token overrides still win." />
+</TypeTable>
+
+```csharp
+o.Theme = ShellDocsTheme.Harbor;
+```
+
+Every preset, and how it combines with your own CSS, is in [Theming](/docs/theming#colour-presets). `Shadcn`, `Fuma` and `Nextra` are obsolete names for `Graphite`.
 
 ## This site's configuration
 

content/docs/getting-started/installation.md

@@ -59,8 +59,8 @@ dotnet add package ShellDocs.Tokens --prerelease
 <CodeTab Label="PackageReference">
 
 ```xml
-<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
-<PackageReference Include="ShellDocs.Tokens" Version="0.1.17-alpha" />
+<PackageReference Include="ShellDocs.Components" Version="0.1.18-alpha" />
+<PackageReference Include="ShellDocs.Tokens" Version="0.1.18-alpha" />
 ```
 
 </CodeTab>
@@ -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>