ShellDocs.Templates 0.1.9-alpha

This is a prerelease version of ShellDocs.Templates.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package ShellDocs.Templates --version 0.1.9-alpha
                    
NuGet\Install-Package ShellDocs.Templates -Version 0.1.9-alpha
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ShellDocs.Templates" Version="0.1.9-alpha" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ShellDocs.Templates" Version="0.1.9-alpha" />
                    
Directory.Packages.props
<PackageReference Include="ShellDocs.Templates" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ShellDocs.Templates --version 0.1.9-alpha
                    
#r "nuget: ShellDocs.Templates, 0.1.9-alpha"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ShellDocs.Templates@0.1.9-alpha
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ShellDocs.Templates&version=0.1.9-alpha&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=ShellDocs.Templates&version=0.1.9-alpha&prerelease
                    
Install as a Cake Tool

ShellDocs

The docs framework for .NET. Markdown-driven documentation sites with live Blazor component previews, versioned docs, Cmd+K search, and a static export. Styled with shadcn-shaped design tokens and composable with any Blazor component library. The fumadocs / shadcn pattern, ported to .NET.

NuGet — alpha: APIs may change between minor versions. See the CHANGELOG and ROADMAP.

Quick start

# Install the CLI (once)
dotnet tool install -g ShellDocs.CLI --prerelease

# From your repo root: scaffold a Blazor Web App in docs/<RepoFolder>.Docs
shelldocs init
cd docs/<RepoFolder>.Docs

# Add pages (or drop .md files into content/docs/)
shelldocs add component Button
shelldocs add guide getting-started

# Run with hot reload on http://localhost:5000
shelldocs dev

# Prerender a static site into publish/
shelldocs build

Already have a Blazor project? Run shelldocs init --attach inside it: it adds the packages and content, and writes SHELLDOCS_SETUP.md with the Program.cs / App.razor snippets instead of editing your code.

What you get

  • Markdown-first authoring. YAML frontmatter, Shiki-highlighted code fences, live razor:preview examples, inline component tags mid-prose.
  • File-based navigation. Drop a .md in content/docs/ and it's a page. Sidebar, breadcrumb, prev/next and TOC come from the folder tree; meta.json controls order, dividers, subsections and hidden pages.
  • Cmd+K search across titles, headings and page text, with body snippets. The index is built in memory at startup, so there's no external service; search needs a running Blazor app (it isn't available in the static export).
  • Blazor-native. Your components render as real Razor components, not iframes.
  • Composable. Bring your own component library (ShellUI, MudBlazor, Radzen, hand-rolled) and register it in one line:
    o.RegisterComponentsFromAssembly<MyLib.Button>();
    
    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. Search, the theme-toggle button, desktop sidebar collapse and stateful demos need a running Blazor app.

Versioned docs

Put each version in its own content folder with the same sub-structure (content/docs/v0.3/..., content/docs/v0.2.1/...; dots in folder names are fine) and register them:

o.AddVersion("v0.3",   "v0.3.0", "/docs/v0.3",   "Current stable", latest: true);
o.AddVersion("v0.2.1", "v0.2.1", "/docs/v0.2.1", "Previous release");

// "{version}" in a package root resolves to the current version's Id.
o.AddPackage("shellui.cli", "ShellUI.CLI", "Command line", "/docs/{version}/cli", icon);

The current version is the one whose RootUrl prefixes the path (segment-aware), otherwise the latest one. With 2+ versions a <VersionSelector /> renders under the package selector (and in the mobile drawer; in the TopNav layout it sits in the header).

  • Switching versions keeps the same page when it exists, else the current package's root, else the version's first page.
  • Switching packages keeps the version.
  • Inside a version, the sidebar shows only that version's tree, prev/next never crosses into another version, and search shows the current version plus pages outside every version.
  • Outside a version, the sidebar leaves the version folders to the selector.
  • Breadcrumbs leave out the version folder.

It's all server-rendered links plus shelldocs.js, so it works on static hosts.

Routes declared as /docs/{*Path:nonfile} don't match a URL whose last segment has a dot (/docs/v0.2.1). Pages below it (/docs/v0.2.1/introduction) are fine, and the selectors never link to a bare version root unless it has an index.md. If you add one, drop :nonfile from the route.

Component previews

  • Preview | Code toolbar on every example, with copy and a ⋯ menu: Open in new tab, Report a bug, Suggest something. The issue links go to https://github.com/{GitHubRepo}/issues/new, pre-filled with the example and page URL; point them elsewhere with o.IssueTrackerUrl.

  • razor:preview fences render everything. Several sibling components, HTML wrappers (<div class="flex gap-2">…</div>) and text render in order inside one frame, and the Code tab shows the whole fence.

  • Razor-shaped attribute values work: Variant="ButtonVariant.Destructive", @ButtonVariant.Destructive, @true, @42, [Flags] values as Bold | Italic.

  • Attributes a static preview can't evaluate are skipped, not fatal: OnClick="HandleClick", @onclick, @bind-*, @ref, non-primitive parameter types, unparseable values. Each logs a warning and the component still renders.

  • Inline code stays code. `<Button>` in prose renders as literal code, not a component.

  • Stateful demos from real files. For demos that need @code (dialogs, bound selects, toasts, charts with data), write a .razor component, register it, and drop <DemoPreview Component="ButtonClickDemo" Title="Optional" /> into markdown. The Code tab shows {DemoSourceRoot}/**/ButtonClickDemo.razor:

    o.RegisterComponentsFromAssembly<App>("MyDocs.Demos");
    o.DemoSourceRoot = Path.Combine(builder.Environment.ContentRootPath, "Demos");
    

    The Razor SDK drops .razor files from build/publish output, so ship them explicitly. Use a None item, because Content Update doesn't survive publish:

    <None Include="Demos/**/*.razor" CopyToOutputDirectory="PreserveNewest" CopyToPublishDirectory="PreserveNewest" />
    

Package family

Package Purpose
ShellDocs.CLI Global tool: shelldocs init, add, dev, build
ShellDocs.Components Razor class library: layouts and chrome (sidebar, header, search, TOC, version / package selectors) and the content primitives. Icons via ShellIcons.Blazor
ShellDocs.Markdown Markdig pipeline: frontmatter, razor:preview fences, inline component tags, the type registry
ShellDocs.Core Navigation graph, meta.json, search index, URL helpers. No UI
ShellDocs.Tokens Design-token CSS variables, shadcn-compatible names for interop with ShellUI and Tailwind-shaped design systems
ShellDocs.Templates Files and snippets emitted by shelldocs init and shelldocs add

Docs

Contributing

The alpha is API-fluid: we're taking freedom to break minor versions until 1.0. Bug reports and dogfood-driven fixes are welcome via issues. A proper CONTRIBUTING.md lands with the 0.2.0-alpha cut.

License

MIT. Do whatever you want, no warranty.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.19-alpha 65 10/21/2026
0.1.18-alpha 62 10/20/2026
0.1.17-alpha 71 10/14/2026
0.1.16-alpha 66 10/14/2026
0.1.15-alpha 66 10/11/2026
0.1.14-alpha 69 10/10/2026
0.1.13-alpha 63 10/10/2026
0.1.12-alpha 67 10/4/2026
0.1.11-alpha 68 10/3/2026
0.1.10-alpha 71 10/2/2026
0.1.9-alpha 65 10/2/2026
0.1.8-alpha 64 10/2/2026
0.1.7-alpha 118 9/7/2026
0.1.6-alpha 84 8/29/2026
0.1.5-alpha 88 8/29/2026
0.1.3-alpha 97 8/11/2026
0.1.2-alpha 91 7/28/2026
0.1.1-alpha 93 7/25/2026
0.1.0-alpha 121 7/25/2026