# ShellDocs > ShellDocs is a docs framework for .NET: Markdown pages, live Blazor component previews, search and a static export, in a Blazor Web App. ## Rules for AI agents Read these before building or changing a ShellDocs site. 1. **Install with the CLI.** `dotnet tool install -g ShellDocs.CLI --prerelease`, then `shelldocs init` for a new site or in an existing Blazor Web App. Keep the `ShellDocs.*` package versions and the CLI version the same. 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. 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. The [full text](https://shelldocs.shellui.dev/llms-full.txt) has every page below in one file. ## Pages - [Introduction](https://shelldocs.shellui.dev/docs/introduction.md): What ShellDocs is, why it exists, and where it fits in the .NET ecosystem. ## Getting Started - [Installation](https://shelldocs.shellui.dev/docs/getting-started/installation.md): Install the ShellDocs CLI, add the framework to a Blazor project. Install: `dotnet tool install -g ShellDocs.CLI --prerelease` - [Quick start](https://shelldocs.shellui.dev/docs/getting-started/quick-start.md): From zero to a working docs site in five minutes. - [Project structure](https://shelldocs.shellui.dev/docs/getting-started/project-structure.md): What ShellDocs scaffolds, and what each folder does. - [Configuration](https://shelldocs.shellui.dev/docs/getting-started/configuration.md): Every option on ShellDocsOptions. Site details, layout, navigation, packages, versions, redirects, branding and component registration. ## Authoring - [Authoring](https://shelldocs.shellui.dev/docs/authoring.md): How to write pages. Markdown, frontmatter, fenced code, live component demos, inline component tags, navigation. - [Frontmatter](https://shelldocs.shellui.dev/docs/authoring/frontmatter.md): YAML metadata at the top of every page. What ShellDocs reads, and what's free for your own use. - [Fenced code](https://shelldocs.shellui.dev/docs/authoring/fenced-code.md): Regular code fences: language detection, copy button, Shiki syntax highlighting. Install: `dotnet add package ShellDocs.Components --prerelease` - [razor:preview](https://shelldocs.shellui.dev/docs/authoring/razor-preview.md): The fence that renders as a live example with Preview and Code tabs. - [Inline component tags](https://shelldocs.shellui.dev/docs/authoring/component-tags.md): Write a component tag straight into the page. It renders as the real component, and its body is markdown. Install: `dotnet tool install -g ShellDocs.CLI --prerelease` - [Navigation](https://shelldocs.shellui.dev/docs/authoring/navigation.md): How ShellDocs builds the sidebar. meta.json, order, dividers, subsections, hidden pages. ## Components - [Callout](https://shelldocs.shellui.dev/docs/components/callout.md): Info / warning / danger / tip / success box with icon, title, and body. - [Card](https://shelldocs.shellui.dev/docs/components/card.md): A titled, described tile: linkable, groupable, iconable. The building block behind CardGrid. - [CardGrid](https://shelldocs.shellui.dev/docs/components/card-grid.md): Responsive grid wrapper for Card / LinkCard children. - [LinkCard](https://shelldocs.shellui.dev/docs/components/link-card.md): An always-clickable card with a trailing arrow glyph. For "next" tiles at the bottom of a page. - [Steps](https://shelldocs.shellui.dev/docs/components/steps.md): Numbered ordered list with a vertical rail. For walk-throughs where sequence matters. Install: `dotnet add package ShellDocs.Components --prerelease` - [Tabs](https://shelldocs.shellui.dev/docs/components/tabs.md): Keyboard-navigable tabs for parallel content, with sync groups that follow the reader across pages. - [CodeGroup](https://shelldocs.shellui.dev/docs/components/code-group.md): Tabbed set of code blocks with site-wide sync via SyncKey. For "same thing in three package managers.". Install: `dotnet add package ShellDocs.Components --prerelease` - [FileTree](https://shelldocs.shellui.dev/docs/components/file-tree.md): Recursive folder/file diagram. For showing project layout without a screenshot. - [TypeTable](https://shelldocs.shellui.dev/docs/components/type-table.md): A four-column props / API table. What every "Props" section on this site is built with. - [AutoTypeTable](https://shelldocs.shellui.dev/docs/components/auto-type-table.md): A props table generated from a component's parameters, defaults and XML doc comments. - [PreviewFrame](https://shelldocs.shellui.dev/docs/components/preview-frame.md): The frame around every live example. Preview and Code tabs, a copy button, an actions menu, and three layouts. - [DemoPreview](https://shelldocs.shellui.dev/docs/components/demo-preview.md): Shows a demo component from your docs project with its .razor file as the source. - [ComponentPreview](https://shelldocs.shellui.dev/docs/components/component-preview.md): A live preview written as a tag. Names the component in an attribute and passes the rest through. - [Code tabs on previews](https://shelldocs.shellui.dev/docs/components/code-tabs.md): Replace a preview's Code panel with tabs you write, switch them together across the site, and add a page-level switch and a caption. - [IframePreview](https://shelldocs.shellui.dev/docs/components/iframe-preview.md): Shows another page in the Preview panel, with the same toolbar, code tabs and theme as the rest of the site. ## Guides - [Documenting a component library](https://shelldocs.shellui.dev/docs/guides/component-libraries.md): Register your own Blazor components, preview them live, and generate their props tables. - [Versioning](https://shelldocs.shellui.dev/docs/guides/versioning.md): Keep one docs tree per released version, with a version selector and chrome that stays inside the version you are reading. - [Redirects](https://shelldocs.shellui.dev/docs/guides/redirects.md): Folder URLs, version roots and moved pages redirect instead of returning a missing page. - [Search](https://shelldocs.shellui.dev/docs/guides/search.md): How search works on a .NET host and on a static export, and how to open it from your own markup or script. - [AI agents (llms.txt)](https://shelldocs.shellui.dev/docs/guides/llms-txt.md): Serve the docs as llms.txt, every page as Markdown and instruction files for Claude Code, Cursor, Copilot and other coding agents. - [Not-found page](https://shelldocs.shellui.dev/docs/guides/not-found.md): DocsNotFound answers HTTP 404 for a URL with no page, and shelldocs build turns it into 404.html. - [Deployment](https://shelldocs.shellui.dev/docs/guides/deployment.md): Publish as a static site or run on a .NET host. What works where, and a GitHub Pages workflow you can copy. Install: `dotnet tool install -g ShellDocs.CLI --prerelease` ## Cli - [shelldocs init](https://shelldocs.shellui.dev/docs/cli/init.md): Scaffold a fresh docs site OR attach ShellDocs to an existing Blazor project. - [shelldocs add](https://shelldocs.shellui.dev/docs/cli/add.md): Scaffold a starter .md page from a template into content/. - [shelldocs dev](https://shelldocs.shellui.dev/docs/cli/dev.md): Start the dev server with hot-reload for .md, .razor, and .cs changes. - [shelldocs build](https://shelldocs.shellui.dev/docs/cli/build.md): Export the site as static files. Prerenders every page, writes redirects, and can add a sitemap and social meta tags. ## Pages - [Theming](https://shelldocs.shellui.dev/docs/theming.md): Override tokens, ship a brand logo, swap the layout variant, register a custom stylesheet. How to make a ShellDocs site look like yours. ## Packages - [ShellDocs.Components](https://shelldocs.shellui.dev/docs/packages/components.md): The Razor Class Library that ships every chrome piece and every markdown-authorable primitive. Where the pixels come from. Install: `dotnet add package ShellDocs.Components --prerelease` - [ShellDocs.Markdown](https://shelldocs.shellui.dev/docs/packages/markdown.md): The Markdig pipeline behind every rendered page. Frontmatter, razor:preview fences, inline Razor tags, per-property type coercion. Install: `dotnet add package ShellDocs.Markdown --prerelease` - [ShellDocs.Core](https://shelldocs.shellui.dev/docs/packages/core.md): Navigation graph, search index, plain-text extraction. The routing and search brain. No UI, no rendering, pure model. Install: `dotnet add package ShellDocs.Core --prerelease` - [ShellDocs.CLI](https://shelldocs.shellui.dev/docs/packages/cli.md): The command-line tool. shelldocs init, add, dev, build. The daily-driver surface for scaffolding, authoring, and shipping. Install: `dotnet tool install -g ShellDocs.CLI --prerelease` - [ShellDocs.Tokens](https://shelldocs.shellui.dev/docs/packages/tokens.md): The design-system CSS variables. shadcn-compatible names, drop-in interop with ShellUI and any Tailwind-shaped design system. Install: `dotnet add package ShellDocs.Tokens --prerelease`