From acef38232adaece67911d41ae061f5fcc3ddd35c Mon Sep 17 00:00:00 2001 From: Shephard Tseisi Date: Wed, 21 Oct 2026 06:55:45 +0200 Subject: [PATCH 1/4] chore: bump ShellDocs to 0.1.18-alpha The four packages and the version strings in the content and README. The home page's terminal replay shows graphite, the theme shelldocs init picks by default since 0.1.18. --- README.md | 2 +- ShellDocs.Site.csproj | 8 ++++---- content/docs/authoring/fenced-code.md | 2 +- content/docs/components/code-group.md | 8 ++++---- content/docs/getting-started/installation.md | 4 ++-- content/docs/guides/deployment.md | 2 +- content/docs/introduction.md | 2 +- content/docs/packages/cli.md | 2 +- content/docs/packages/components.md | 2 +- content/docs/packages/core.md | 2 +- content/docs/packages/markdown.md | 2 +- content/docs/packages/tokens.md | 2 +- wwwroot/cli-replay.js | 4 ++-- 13 files changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 402d150..5554618 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/ShellDocs.Site.csproj b/ShellDocs.Site.csproj index 2f81eeb..588a50e 100644 --- a/ShellDocs.Site.csproj +++ b/ShellDocs.Site.csproj @@ -19,10 +19,10 @@ - - - - + + + + diff --git a/content/docs/authoring/fenced-code.md b/content/docs/authoring/fenced-code.md index 98f29e9..16caeb7 100644 --- a/content/docs/authoring/fenced-code.md +++ b/content/docs/authoring/fenced-code.md @@ -109,7 +109,7 @@ dotnet add package ShellDocs.Components --prerelease ```xml - + ``` diff --git a/content/docs/components/code-group.md b/content/docs/components/code-group.md index d4d7efc..0ecbd47 100644 --- a/content/docs/components/code-group.md +++ b/content/docs/components/code-group.md @@ -21,7 +21,7 @@ dotnet add package ShellDocs.Components --prerelease ```xml - + ``` @@ -41,7 +41,7 @@ dotnet add package ShellDocs.Components --prerelease ```xml - + ``` @@ -63,7 +63,7 @@ dotnet add package ShellDocs.Core --prerelease ```xml - + ``` @@ -80,7 +80,7 @@ dotnet add package ShellDocs.Markdown --prerelease ```xml - + ``` diff --git a/content/docs/getting-started/installation.md b/content/docs/getting-started/installation.md index 6dde76c..390828d 100644 --- a/content/docs/getting-started/installation.md +++ b/content/docs/getting-started/installation.md @@ -59,8 +59,8 @@ dotnet add package ShellDocs.Tokens --prerelease ```xml - - + + ``` diff --git a/content/docs/guides/deployment.md b/content/docs/guides/deployment.md index 310c887..a372858 100644 --- a/content/docs/guides/deployment.md +++ b/content/docs/guides/deployment.md @@ -87,7 +87,7 @@ jobs: - uses: actions/setup-dotnet@v4 with: global-json-file: global.json - - run: dotnet tool install -g ShellDocs.CLI --version 0.1.17-alpha + - run: dotnet tool install -g ShellDocs.CLI --version 0.1.18-alpha - run: shelldocs build --site-url https://docs.example.com - run: echo "docs.example.com" > publish/CNAME - run: touch publish/.nojekyll diff --git a/content/docs/introduction.md b/content/docs/introduction.md index 9839b0b..a419576 100644 --- a/content/docs/introduction.md +++ b/content/docs/introduction.md @@ -9,7 +9,7 @@ order: 1 **ShellDocs is the docs framework for .NET.** Beautiful, animated, `Cmd+K`-searchable documentation sites, powered by Blazor and Tailwind. Compose with ShellUI (or any Blazor component library) : like fumadocs composes with shadcn/ui in the React world. -ShellDocs is in alpha; these docs cover `0.1.17-alpha`. The primitive surface is stable enough to build real docs sites : this site is built with ShellDocs itself. Expect small API changes before `1.0`. +ShellDocs is in alpha; these docs cover `0.1.18-alpha`. The primitive surface is stable enough to build real docs sites : this site is built with ShellDocs itself. Expect small API changes before `1.0`. ## Why ShellDocs exists diff --git a/content/docs/packages/cli.md b/content/docs/packages/cli.md index 1627073..3a3711c 100644 --- a/content/docs/packages/cli.md +++ b/content/docs/packages/cli.md @@ -89,7 +89,7 @@ Publishes the project, starts it locally, saves every page as static HTML, write ## Version discipline -`shelldocs init` scaffolds package references at the CLI's own version, read from its assembly. A project scaffolded with CLI `0.1.17-alpha` references the `0.1.17-alpha` packages. In CI, pin the tool to the same version your project references. +`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. ## Learn more diff --git a/content/docs/packages/components.md b/content/docs/packages/components.md index 71c7761..94fa31e 100644 --- a/content/docs/packages/components.md +++ b/content/docs/packages/components.md @@ -25,7 +25,7 @@ dotnet add package ShellDocs.Components --prerelease ```xml - + ``` diff --git a/content/docs/packages/core.md b/content/docs/packages/core.md index 7b2969a..8f434c5 100644 --- a/content/docs/packages/core.md +++ b/content/docs/packages/core.md @@ -25,7 +25,7 @@ dotnet add package ShellDocs.Core --prerelease ```xml - + ``` diff --git a/content/docs/packages/markdown.md b/content/docs/packages/markdown.md index 680cbe2..78fd3d9 100644 --- a/content/docs/packages/markdown.md +++ b/content/docs/packages/markdown.md @@ -25,7 +25,7 @@ dotnet add package ShellDocs.Markdown --prerelease ```xml - + ``` diff --git a/content/docs/packages/tokens.md b/content/docs/packages/tokens.md index 6f49cd8..a5f4b06 100644 --- a/content/docs/packages/tokens.md +++ b/content/docs/packages/tokens.md @@ -25,7 +25,7 @@ dotnet add package ShellDocs.Tokens --prerelease ```xml - + ``` diff --git a/wwwroot/cli-replay.js b/wwwroot/cli-replay.js index 045abb1..c309767 100644 --- a/wwwroot/cli-replay.js +++ b/wwwroot/cli-replay.js @@ -1,5 +1,5 @@ // Replays `shelldocs init` and `shelldocs build` in elements marked [data-cli-replay]. -// The lines are the CLI's real output for a new site (ShellDocs.CLI 0.1.17-alpha), shortened. +// The lines are the CLI's real output for a new site (ShellDocs.CLI 0.1.18-alpha), shortened. (function () { 'use strict'; @@ -20,7 +20,7 @@ { header: 'the docs framework for .NET' }, { line: `${dim('Mode')} create`, wait: 80 }, { line: `${dim('Site name')} MyDocs`, wait: 80 }, - { line: `${dim('Theme')} shadcn`, wait: 80 }, + { line: `${dim('Theme')} graphite`, wait: 80 }, { line: '', wait: 0 }, { line: `${dim('$')} ${c('dotnet new blazor -o MyDocs')}` }, { spin: 'Creating the Blazor Web App...', ms: 1400 }, From c3f2077c6a7eeeb55e5222298ede1588cce172c7 Mon Sep 17 00:00:00 2001 From: Shephard Tseisi Date: Wed, 21 Oct 2026 06:55:51 +0200 Subject: [PATCH 2/4] docs: colour presets ShellDocs 0.1.18 adds seven palettes (o.Theme, init --theme). The theming page gets a Colour presets section with a live demo: wwwroot/demos/presets.html loads tokens.css in an IframePreview and switches presets, since a preset recolours the whole document it is on. The 'Theme has no effect' text goes from theming, configuration and init; the tokens and CLI package pages mention the presets. The site stays on Graphite. --- content/docs/cli/init.md | 4 +- content/docs/getting-started/configuration.md | 14 ++- content/docs/packages/cli.md | 1 + content/docs/packages/tokens.md | 4 + content/docs/theming.md | 52 ++++++++-- wwwroot/demos/presets.html | 95 +++++++++++++++++++ 6 files changed, 158 insertions(+), 12 deletions(-) create mode 100644 wwwroot/demos/presets.html diff --git a/content/docs/cli/init.md b/content/docs/cli/init.md index 8fbca12..b84840f 100644 --- a/content/docs/cli/init.md +++ b/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. -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`. Adds the `_content/ShellDocs.Tokens/tokens.css` and component CSS links, the theme-bootstrap script, and `shelldocs.js` + Shiki loader. Also switches `` to `` 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`, - + ## Exit codes diff --git a/content/docs/getting-started/configuration.md b/content/docs/getting-started/configuration.md index 8f5efb8..0b53e96 100644 --- a/content/docs/getting-started/configuration.md +++ b/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). + + + + +```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 diff --git a/content/docs/packages/cli.md b/content/docs/packages/cli.md index 3a3711c..69c18a5 100644 --- a/content/docs/packages/cli.md +++ b/content/docs/packages/cli.md @@ -40,6 +40,7 @@ Two modes. **Create** (default) scaffolds a fresh Blazor Web App under `docs/ +## Colour presets + +`tokens.css` also holds six tinted palettes next to the default (Graphite): Harbor, Lagoon, Forest, Savanna, Ember and Jacaranda, each with light and dark values. A ShellDocs site picks one with `o.Theme`; using the package on its own, put `data-shelldocs-theme="harbor"` on any element of the page. See [Theming](/docs/theming#colour-presets). + ## Overriding tokens Tokens are CSS custom properties : override anywhere with normal CSS specificity. diff --git a/content/docs/theming.md b/content/docs/theming.md index 12b4f02..e9a1d3a 100644 --- a/content/docs/theming.md +++ b/content/docs/theming.md @@ -1,16 +1,58 @@ --- title: Theming -description: Override tokens, ship a brand logo, swap the layout variant, register a custom stylesheet. How to make a ShellDocs site look like yours. +description: Pick a colour preset, override tokens, ship a brand logo, swap the layout variant, register a custom stylesheet. How to make a ShellDocs site look like yours. order: 6 --- # Theming -ShellDocs is designed to be re-skinnable via CSS variables : the shipped `tokens.css` sets every color, radius, spacing, and font stack, and the entire chrome cascades from there. Override the tokens, and every primitive follows. +ShellDocs is designed to be re-skinnable via CSS variables : the shipped `tokens.css` sets every color, radius, spacing, and font stack, and the entire chrome cascades from there. Override the tokens, and every primitive follows. For a tinted palette without writing any CSS, pick a colour preset. + +## Colour presets + +```csharp +builder.Services.AddShellDocs(o => +{ + o.Theme = ShellDocsTheme.Harbor; +}); +``` + +| Preset | Colour | +|---|---| +| `Graphite` | Neutral greys. The default, and what this site uses. | +| `Harbor` | Blue | +| `Lagoon` | Teal | +| `Forest` | Green | +| `Savanna` | Amber on sand | +| `Ember` | Red-orange | +| `Jacaranda` | Purple | + +Pick one below to see it. Switch the site between light and dark and the example follows. + + + +A preset tints the backgrounds, borders and muted text with its hue, and uses its colour for the active sidebar item, focus rings, link underlines, the primary button and other accents. Each one has a light and a dark palette, and every text colour keeps a contrast of at least 4.5:1. The callout colours (`--info`, `--warning`, `--error`, `--success`) stay the same in every preset. + +`shelldocs init --theme harbor` writes the `o.Theme` line for a new site. Without `--theme` the site gets Graphite, with the line as a commented-out example. + +### How a preset is applied + +The presets are CSS in `tokens.css`, one light and one dark block each, keyed on a `data-shelldocs-theme` attribute: + +```css +:root:has(:where([data-shelldocs-theme="harbor"])) { --primary: oklch(0.520 0.170 255); /* … */ } +:root.dark:has(:where([data-shelldocs-theme="harbor"])) { /* … */ } +``` + +`o.Theme` makes `DocsLayout` and `HomeLayout` render that attribute, so a preset works on a static export too. The `:where()` keeps the rules as specific as plain `:root` and `:root.dark`, so [your own token overrides](#overriding-tokens) in a later stylesheet still win: pick the preset closest to your brand and override the few tokens that differ. A page that uses `ShellDocs.Tokens` without the layouts can put the attribute on any element. + + +Before `0.1.18-alpha`, `ShellDocsTheme` had the values `Shadcn`, `Fuma` and `Nextra`, and none of them changed anything. They are now obsolete aliases of `Graphite`: code that sets one still compiles, with a warning, and gets the default palette. `shelldocs init --theme` takes the preset names. + ## The token file -`ShellDocs.Tokens` ships one CSS file : `_content/ShellDocs.Tokens/tokens.css`. It declares two `:root` blocks : the light-mode defaults and the `:root.dark` overrides that kick in when the theme toggle is set to dark. +`ShellDocs.Tokens` ships one CSS file : `_content/ShellDocs.Tokens/tokens.css`. It declares two `:root` blocks : the light-mode defaults (Graphite) and the `:root.dark` overrides that kick in when the theme toggle is set to dark. After them come the [colour presets](#colour-presets). Each variable value is set via `hsl(...)` or `oklch(...)` for perceptual uniformity. The shadcn-compatible naming (`--background`, `--foreground`, `--primary`, `--muted`, …) means any component library that speaks the same vocabulary drops in without extra mapping. @@ -143,10 +185,6 @@ Both layouts share the same token surface : switching is a one-line change. Every ShellDocs primitive picks it up automatically : no per-component override needed. -## The `--theme` flag - -`shelldocs init --theme` and `ShellDocsOptions.Theme` accept `shadcn`, `fuma` and `nextra`, but have no effect in this release. Every site starts from the same `tokens.css`. Restyle with token overrides. - ## Keeping page typography out Page content is styled through the `shelldocs-prose` class: paragraph spacing, list padding, heading sizes, link underlines. Those rules skip any element with the `not-prose` class and everything inside it. Preview frames carry it already, so components in examples are not restyled. Add it to your own markup when you drop custom HTML into a page and want it left alone: diff --git a/wwwroot/demos/presets.html b/wwwroot/demos/presets.html new file mode 100644 index 0000000..2029479 --- /dev/null +++ b/wwwroot/demos/presets.html @@ -0,0 +1,95 @@ + + + + + + Colour presets + + + + + +
+
+ +
+

The Graphite preset

+

Muted text, borders and backgrounds take the preset's hue. Links like this one and the active sidebar item use its colour.

+
+ + + +
+
A card: o.Theme = ShellDocsTheme.Graphite;
+
+
+ + + From 17a52ccacde322643fd5a449cf97806db60938a6 Mon Sep 17 00:00:00 2001 From: Shephard Tseisi Date: Wed, 21 Oct 2026 06:55:53 +0200 Subject: [PATCH 3/4] 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. --- README.md | 4 +- content/docs/cli/build.md | 7 +- content/docs/cli/meta.json | 2 +- content/docs/cli/preview.md | 73 ++++++++++++++++++++ content/docs/getting-started/installation.md | 2 +- content/docs/getting-started/quick-start.md | 2 +- content/docs/guides/deployment.md | 9 +++ content/docs/introduction.md | 2 +- content/docs/packages/cli.md | 13 +++- 9 files changed, 104 insertions(+), 10 deletions(-) create mode 100644 content/docs/cli/preview.md diff --git a/README.md b/README.md index 5554618..e743a8f 100644 --- a/README.md +++ b/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 + demos/ static pages shown with (theme frame, colour presets) cli-replay.js the terminal replay on the home page copy-button.js copy buttons marked with data-copy Llms/ diff --git a/content/docs/cli/build.md b/content/docs/cli/build.md index 137ce86..e4c888e 100644 --- a/content/docs/cli/build.md +++ b/content/docs/cli/build.md @@ -59,7 +59,7 @@ Rewrites the base href, replaces `404.html` with the home page, and adds the sit -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 + diff --git a/content/docs/cli/meta.json b/content/docs/cli/meta.json index 0da0cc5..04754e4 100644 --- a/content/docs/cli/meta.json +++ b/content/docs/cli/meta.json @@ -1,4 +1,4 @@ { "title": "CLI", - "pages": ["init", "add", "dev", "build"] + "pages": ["init", "add", "dev", "build", "preview"] } diff --git a/content/docs/cli/preview.md b/content/docs/cli/preview.md new file mode 100644 index 0000000..3816625 --- /dev/null +++ b/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 ] [--output ] [--port ] [--base-href ] +``` + +## 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 + + + + + + + + +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 + + + + + + + + +## Exit codes + + + + + + +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 ` placeholder. + +## See also + + + + + diff --git a/content/docs/getting-started/installation.md b/content/docs/getting-started/installation.md index 390828d..8a74984 100644 --- a/content/docs/getting-started/installation.md +++ b/content/docs/getting-started/installation.md @@ -71,7 +71,7 @@ dotnet add package ShellDocs.Tokens --prerelease ## The package family - + diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started/quick-start.md index 1f1e791..7a1c1c9 100644 --- a/content/docs/getting-started/quick-start.md +++ b/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. diff --git a/content/docs/guides/deployment.md b/content/docs/guides/deployment.md index a372858..b0e66b4 100644 --- a/content/docs/guides/deployment.md +++ b/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 + diff --git a/content/docs/introduction.md b/content/docs/introduction.md index a419576..4cd76f0 100644 --- a/content/docs/introduction.md +++ b/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 - + diff --git a/content/docs/packages/cli.md b/content/docs/packages/cli.md index 69c18a5..5e1fc19 100644 --- a/content/docs/packages/cli.md +++ b/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 + ## `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. From 8285db6ebef2409b11d97968bce66f76c58161a9 Mon Sep 17 00:00:00 2001 From: Shephard Tseisi Date: Wed, 21 Oct 2026 06:56:07 +0200 Subject: [PATCH 4/4] docs: entities in attributes are decoded; state services removed Since 0.1.18 HTML entities in component attribute values are decoded, so the inline-tags page, the Card page and the agent rules no longer say they stay literal. The search page says SearchState, SidebarCollapseState and MobileNavState are gone. --- Llms/agent-rules.md | 2 +- content/docs/authoring/component-tags.md | 10 ++++++++-- content/docs/components/card.md | 2 -- content/docs/guides/search.md | 2 +- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/Llms/agent-rules.md b/Llms/agent-rules.md index b2d623d..4ffe390 100644 --- a/Llms/agent-rules.md +++ b/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 ` 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.** ``, `` / ``, `` / ``, `` / `` / ``, ``, ``, `` / `` and ``. When a site's own library has a component of the same name, the `Docs` prefix (``) still reaches the built-in. 4. **Live examples:** a ```` ```razor:preview ```` fence, ``, or `` for a `.razor` file under `DemoSourceRoot`. A `razor:preview` body is Razor, not Markdown: use `` and ``, not backticks and `**`. Components used in Markdown must be registered with `RegisterComponent()` or `RegisterComponentsFromAssembly()`. -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 (`&`, `"`). For a value that holds double quotes, wrap it in single quotes or write `"`. 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. diff --git a/content/docs/authoring/component-tags.md b/content/docs/authoring/component-tags.md index eab8e9d..7a570ab 100644 --- a/content/docs/authoring/component-tags.md +++ b/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: - + - + +```markdown + +``` + +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 diff --git a/content/docs/components/card.md b/content/docs/components/card.md index 6938fda..9c3c033 100644 --- a/content/docs/components/card.md +++ b/content/docs/components/card.md @@ -42,8 +42,6 @@ The same attribute works on a `Card` written straight into the page: -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. diff --git a/content/docs/guides/search.md b/content/docs/guides/search.md index afc301b..7b70add 100644 --- a/content/docs/guides/search.md +++ b/content/docs/guides/search.md @@ -71,7 +71,7 @@ shelldocsSearch.close(); ## Upgrading from before 0.1.15 -`shelldocsSearch.init` is gone. If your own script called it, remove the call: search sets itself up. The `SearchState` service is still registered so existing code compiles, but nothing reads it any more. Open search with `data-search-open` or `shelldocsSearch.open()` instead. +`shelldocsSearch.init` is gone. If your own script called it, remove the call: search sets itself up. Open search with `data-search-open` or `shelldocsSearch.open()`. The `SearchState` service stayed registered until `0.1.17-alpha` so old code compiled, but nothing read it; `0.1.18-alpha` removed it, with `SidebarCollapseState` and `MobileNavState`. Code that injects one needs its own copy. For search to work in a static export, both the packages the site references and the `ShellDocs.CLI` that builds it must be `0.1.15-alpha` or later. `shelldocs build` prints a warning when the site doesn't serve an index.