# ShellDocs.Components

> The Razor Class Library that ships every chrome piece and every markdown-authorable primitive. Where the pixels come from.

Source: https://shelldocs.shellui.dev/docs/packages/components

`ShellDocs.Components` is the visible layer of ShellDocs. Everything you see on a rendered page : the sidebar, the header, the search dialog, the layouts, and every primitive you drop into markdown : lives in this Razor Class Library.

> **You already depend on it**
>
> `shelldocs init` adds `ShellDocs.Components` to your `.csproj` automatically. `ShellDocs.Core` and `ShellDocs.Markdown` come in transitively : nothing else to add.

## Install

**dotnet CLI**

```bash
dotnet add package ShellDocs.Components --prerelease
```

**PackageReference**

```xml
<PackageReference Include="ShellDocs.Components" Version="0.1.17-alpha" />
```

## What's inside

Two categories: **chrome** (the layout, header, sidebar, search : the site's skeleton) and **content primitives** (the components authors drop into markdown).

### Chrome

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `DocsLayout` | `component` |  | Full-page layout. Two variants: TopNav (classic header + sidebar) and Sidebar (floating card, this site's variant). |
| `DocsHeader` | `component` |  | Top nav bar : logo, primary nav links, theme toggle, GitHub link, search trigger. |
| `DocsSidebar` | `component` |  | Sidebar nav tree : auto-populated from the content folder. Collapsible sections, active-path highlighting. |
| `DocsSidebarHeader` | `component` |  | Sidebar top : brand logo + collapse toggle + search field (Sidebar variant only). The collapse is handled by shelldocs.js and remembered in localStorage. |
| `DocsFooter` | `component` |  | Footer band : brand, tagline, socials, columns of links. |
| `DocsMobileBar` | `component` |  | Sticky top bar on mobile : hamburger opens the sidebar drawer. Driven by shelldocs.js, so it works on static hosts. |
| `DocsBreadcrumb` | `component` |  | Trail from root → current page, auto-derived from the nav graph. |
| `TableOfContents` | `component` |  | Right-rail on-this-page nav, scroll-spy indicator. |
| `PrevNextNav` | `component` |  | Bottom-of-page prev/next cards, auto-derived from nav adjacency. |
| `SearchDialog` | `component` |  | Cmd+K modal that searches titles, sections and body text. Ranked in the browser by shelldocs.js, so it works on static hosts. Part of DocsLayout and HomeLayout. |
| `DocsPageActions` | `component` |  | The menu by the page title: Copy page, View as Markdown, Open in Claude, Open in ChatGPT. Shown when EnableLlmsTxt is on. |
| `PackageSelector` | `component` |  | Sidebar dropdown for switching between package families. |
| `VersionSelector` | `component` |  | Dropdown for switching docs version. Shown once two or more versions are registered. |
| `BrandLogo` | `component` |  | Renders your LogoSvg (inline) or LogoLight/LogoDark (URLs), with a placeholder dot fallback. |
| `ThemeToggle` | `component` |  | Sun and moon theme switch. Handled by shelldocs.js, stored in localStorage, follows the dark class on the html element. |

### Content primitives (author these in `.md`)

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `Callout` | `component` |  | Info / warning / danger / tip box with icon, title, body. |
| `Card / CardGrid / LinkCard` | `component` |  | Responsive card family. Cards render as a link when Href is set. |
| `Steps / Step` | `component` |  | Numbered ordered list with a rail; badges centered on the spine. |
| `FileTree / FileTreeItem` | `component` |  | Recursive project-layout diagram with folder/file glyphs. |
| `Tabs / Tab` | `component` |  | Tabbed panels for any content, with sync groups. |
| `CodeGroup / CodeTab` | `component` |  | Tabbed code samples. SyncKey groups switch together across pages. CodeTab also goes inside a preview to replace its Code panel. |
| `TypeTable / TypeRow` | `component` |  | Props / API reference table with type-code chips and required badge. |
| `AutoTypeTable` | `component` |  | Props table generated from a component by reflection and XML doc comments. |
| `PreviewFrame` | `component` |  | The frame around every live example: Preview and Code tabs, copy, actions menu, layouts. |
| `DemoPreview` | `component` |  | Renders a demo component and shows its .razor file as the source. |
| `ComponentPreview` | `component` |  | A live preview written as a tag instead of a fence. |
| `IframePreview` | `component` |  | Shows another page in the Preview panel, with the same toolbar and code tabs. |
| `SyncSwitch` | `component` |  | A row of tabs on the page that switches every block sharing a SyncKey. |
| `DocsNotFound` | `component` |  | The not-found view for DocsPage.razor. Answers HTTP 404. |
| `MarkdownContent` | `component` |  | The renderer itself. DocsPage.razor calls this with the resolved .md document. |

## The layout variant

The two `DocsLayoutVariant` options shape the whole site:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `TopNav` | `DocsLayoutVariant` |  | Classic docs shape : full-width header at the top spanning nav + logo + search, sidebar below on the left, TOC on the right. |
| `Sidebar` | `DocsLayoutVariant` |  | Floating-card sidebar on the left, containing brand + search + nav. Content area is flush to the page background. This site uses it. |

```csharp
o.LayoutVariant = DocsLayoutVariant.Sidebar;   // or TopNav
```

## Auto-chrome

`DocsLayout` auto-renders `<DocsBreadcrumb />`, `<PrevNextNav />`, and `<TableOfContents />` from a shared scoped service (`DocsPageState`). When `MarkdownContent` publishes the current document, all three chrome components pick up the state and render. Your `DocsPage.razor` collapses to a single call:

```razor
@page "/docs/{*Path:nonfile}"
@layout DocsLayout
@inject NavigationGraph Graph
@inject MarkdownRenderer Renderer

@if (_document is not null)
{
    <MarkdownContent Document="@_document" />
}
else
{
    <DocsNotFound />
}

@code {
    [Parameter] public string? Path { get; set; }
    RenderedDocument? _document;

    protected override void OnParametersSet()
    {
        var url = "/docs" + (Path is null ? "" : "/" + Path);
        var node = Graph.ResolveByUrl(url);
        if (node?.Path is not null) _document = Renderer.RenderFile(node.Path);
    }
}
```

No `<TableOfContents Headings="..." />` boilerplate, no `<SectionContent>` slot wiring, no explicit `<PrevNextNav Prev="_prev" Next="_next" />`. All three appear automatically as long as `MarkdownContent` published the current document to state.

## Learn more

- [Callout](https://shelldocs.shellui.dev/docs/components/callout.md): Info / warning / danger / tip.
- [Card](https://shelldocs.shellui.dev/docs/components/card.md): Anchor-or-div cards with icon + title + description.
- [Steps](https://shelldocs.shellui.dev/docs/components/steps.md): Numbered walkthrough with a rail.
- [CodeGroup](https://shelldocs.shellui.dev/docs/components/code-group.md): Tabbed code samples with cross-page sync.
- [FileTree](https://shelldocs.shellui.dev/docs/components/file-tree.md): Recursive project-layout diagram.
- [TypeTable](https://shelldocs.shellui.dev/docs/components/type-table.md): Props / API reference table.