# Introduction

> What ShellDocs is, why it exists, and where it fits in the .NET ecosystem.

Source: https://shelldocs.shellui.dev/docs/introduction

**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.

> **Alpha status**
>
> 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`.

## Why ShellDocs exists

Every .NET UI library ends up hand-rolling its own docs site. MudBlazor, Radzen, AvaloniaUI : each spent months rebuilding a sidebar, a search box, a code block, a theme toggle. None of it was reusable.

ShellDocs is the "just use this" answer. Point it at a folder of markdown, get a working docs site : with the design polish React consumers have taken for granted since fumadocs shipped in 2023.

## What you get

- **Markdown-first authoring**: YAML frontmatter, fenced code blocks with Shiki highlighting, live-rendered razor:preview examples, and inline Razor component tags mid-prose.
- **Auto-wired navigation**: File-based routing. Drop a .md into content/, it becomes a page. Sidebar, breadcrumb, prev/next, TOC : all derived from the tree.
- **Cmd+K search**: Built into the app. Matches titles, descriptions, headings and body text, with snippets. No external search service to set up.
- **Composable**: Bring your own component library. Register in one line via RegisterComponentsFromAssembly. Reference in markdown.
- **Live previews**: Components render as real Razor components, not screenshots, with Preview and Code tabs on every example.
- **Versioned docs**: One content folder per release, a version selector, and navigation that stays inside the version being read.
- **Static site output**: shelldocs build prerenders every page for any static host, with redirects, a sitemap and social meta tags.

## How it looks in practice

Author a page as plain markdown with frontmatter:

````markdown
---
title: Button
description: A pressable UI element.
---

# Button

The `<Button>` component ships in three variants.

## Live example

```razor:preview
<Button Variant="primary">Click me</Button>
```
````

Drop inline components anywhere in prose:

````markdown
<Callout Variant="warning" Title="Heads up">
This behavior changed in `0.2.0`. Older versions used `OnClick` instead of `Pressed`.
</Callout>
````

The whole thing renders : Callout with icon and variant styling, live Button component, syntax-highlighted code samples, working TOC : with zero JavaScript beyond what Blazor and Shiki need.

## The three packages you'll touch most

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `ShellDocs.CLI` | `global tool` |  | shelldocs init, add, dev, build. Installed once, works from any directory. |
| `ShellDocs.Components` | `Razor Class Library` |  | The chrome (layout, sidebar, search, header) and content primitives (Callout, Card, Steps, CodeGroup, TypeTable, more). |
| `ShellDocs.Tokens` | `Razor Class Library` |  | Shared CSS variables : palette + spacing scale. shadcn-compatible names for interop with ShellUI and other design systems. |

## Where to go next

- [Installation](https://shelldocs.shellui.dev/docs/getting-started/installation.md): Install the CLI, scaffold a project, run it locally.
- [Quick start](https://shelldocs.shellui.dev/docs/getting-started/quick-start.md): From zero to a live docs site in five minutes.
- [Component reference](https://shelldocs.shellui.dev/docs/components/callout.md): Callout, Card, Steps, Tabs, CodeGroup, FileTree, TypeTable and the preview primitives.
- [Authoring guide](https://shelldocs.shellui.dev/docs/authoring.md): Frontmatter, razor:preview, inline component tags, navigation.
- [Documenting a component library](https://shelldocs.shellui.dev/docs/guides/component-libraries.md): Register your components, preview them, generate props tables.
- [Deployment](https://shelldocs.shellui.dev/docs/guides/deployment.md): Static export or a .NET host.