# Configuration

> Every option on ShellDocsOptions. Site details, layout, navigation, packages, versions, redirects, branding and component registration.

Source: https://shelldocs.shellui.dev/docs/getting-started/configuration

A ShellDocs site is configured in one place: the `AddShellDocs` call in `Program.cs`.

## The minimum

```csharp
builder.Services.AddShellDocs(o =>
{
    o.ContentRoot = Path.Combine(builder.Environment.ContentRootPath, "content");
    o.SiteName = "MyDocs";
    o.GitHubRepo = "my-org/my-docs";
});
```

That is a working site. The built-in content primitives are registered for you.

## Site details

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `SiteName` (required) | `string` | `empty` | Brand name shown in the header and sidebar. |
| `SiteTagline` | `string?` | `—` | One-line description shown in the footer. |
| `GitHubRepo` | `string?` | `—` | Owner and repository, for example my-org/my-docs. Used for the GitHub link and as the default issue tracker. |
| `SiteUrl` | `string?` | `—` | Absolute address of the deployed site. Used in the links the preview menu builds and in the llms.txt files. |
| `IssueTrackerUrl` | `string?` | `GitHubRepo issues` | Where the preview menu's Report a bug and Suggest something open a new issue. With neither this nor GitHubRepo set, those items are hidden. |
| `ContentRoot` | `string` | `content` | Path to the content folder. |

The sitemap and social meta tags of a static export come from the `--site-url` flag of [shelldocs build](https://shelldocs.shellui.dev/docs/cli/build.md).

## Layout and page header

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `LayoutVariant` | `DocsLayoutVariant` | `TopNav` | TopNav is a header across the top with the sidebar below. Sidebar has no top header; brand and search live in a floating sidebar. This site uses Sidebar. |
| `RenderPageTitle` | `bool` | `false` | Renders the frontmatter title as the page heading, and the description as a lead paragraph, on pages whose body does not start with its own heading. |

```csharp
o.LayoutVariant = DocsLayoutVariant.Sidebar;
o.RenderPageTitle = true;
```

## Header navigation

| Call | Adds |
|---|---|
| `AddNavLink(label, href)` | A link in the primary nav |
| `AddNavMenu(label, items…)` | A dropdown of links, each with an optional description and icon |

```csharp
o.AddNavLink("Docs", "/docs/introduction");
o.AddNavLink("Releases", "https://github.com/my-org/my-lib/releases");

o.AddNavMenu("Learn",
    new NavMenuItem("Getting started", "/docs/getting-started/installation", "Install and scaffold your first site."),
    new NavMenuItem("Authoring", "/docs/authoring", "Write pages in markdown."));
```

On small screens the primary nav becomes a menu behind the hamburger button.

## Package selector

For a product made of several packages, the sidebar can show a selector that jumps between each package's docs.

```csharp
o.AddPackage("mylib.core", "MyLib.Core", "The core library.", "/docs/core");
o.AddPackage("mylib.cli",  "MyLib.CLI",  "The command line.", "/docs/cli");
```

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `id` (required) | `string` |  | Unique identifier. |
| `title` (required) | `string` |  | Name shown in the selector. |
| `description` (required) | `string` |  | Second line in the menu. |
| `rootUrl` (required) | `string` |  | Where selecting the package goes. May contain the version token. |
| `iconPath` | `string?` |  | The d attribute of an SVG path on a 24 by 24 view box. Not a URL. |

The selector is hidden with fewer than two packages. The selected package is the one whose root URL is the longest prefix of the current path.

## Versions

```csharp
o.AddVersion("v2.0",   "v2.0.0", "/docs/v2.0",   "Current stable", latest: true);
o.AddVersion("v1.9.1", "v1.9.1", "/docs/v1.9.1", "Previous release");
```

Registering versions adds a version selector and scopes the sidebar, search, breadcrumb and prev/next links to the version being read. The full walk-through is in [Versioning](https://shelldocs.shellui.dev/docs/guides/versioning.md).

## Redirects

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `EnableRedirects` | `bool` | `true` | Redirects folder URLs, version roots and unversioned URLs to the right page. |
| `AddRedirect(from, to, permanent)` | `method` |  | A rule for moved content. Matches by path segment and covers everything under the source path. Permanent by default. |

```csharp
o.AddRedirect("/docs/setup", "/docs/getting-started/installation");
```

See [Redirects](https://shelldocs.shellui.dev/docs/guides/redirects.md).

## Brand logo

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `LogoSvg` | `string?` | `—` | Inline SVG markup. Use currentColor and one logo serves both themes. Rendered as raw markup, so only pass content you wrote. |
| `LogoLight / LogoDark` | `string?` | `—` | Image URLs for each theme, for logos with fixed colours. |
| `LogoAlt` | `string?` | `SiteName` | Accessible label for the logo. |
| `LogoHeight` | `double` | `1.375` | Height in rem. |
| `SetLogo(url, alt)` | `method` |  | One image for both themes. |
| `SetLogo(light, dark, alt)` | `method` |  | An image per theme. |

```csharp
o.LogoSvg = File.ReadAllText(Path.Combine(builder.Environment.WebRootPath, "brand/logo.svg"));
```

## Registering components

Built-in primitives are always available. Register your own so their tags work in markdown and previews.

| Call | Registers |
|---|---|
| `RegisterComponent<T>()` | One component |
| `RegisterComponent<T>(tagName)` | One component under a different tag name |
| `RegisterComponentsFromAssembly<TMarker>()` | Every public component in the marker's assembly |
| `RegisterComponentsFromAssembly<TMarker>(namespacePrefix)` | Only components in namespaces starting with the prefix |
| `RegisterComponentsFromAssembly<TMarker>(filter)` | Only components the filter accepts |

```csharp
o.RegisterComponentsFromAssembly<MyLib.Button>();
o.RegisterComponentsFromAssembly<App>("MyDocs.Components.Demos");
```

A component of yours with the same name as a built-in wins the tag; the built-in stays available under a `Docs` prefix. Generic components register under their bare name. Mark a component with `[ShellDocsIgnore]` to leave it out. All of this is covered in [Documenting a component library](https://shelldocs.shellui.dev/docs/guides/component-libraries.md).

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `DemoSourceRoot` | `string?` | `—` | Folder searched for the .razor file that DemoPreview shows as source. |

## Previews

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `PreviewCaption` | `string?` | `—` | A note shown in the toolbar of every preview. A preview's own Caption replaces it. |
| `AddSyncSwitch(syncKey, options)` | `method` |  | Adds a row of tabs to every page whose blocks use that SyncKey. Needs at least two options; the first is the default. |

```csharp
o.PreviewCaption = "Rendered with Blazor";
o.AddSyncSwitch("platform", "MAUI", "Avalonia");
```

Both are covered in [Code tabs on previews](https://shelldocs.shellui.dev/docs/components/code-tabs.md).

## AI agents

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `EnableLlmsTxt(configure)` | `method` |  | Serves /llms.txt, /llms-full.txt, every page as Markdown and agent instruction files, and adds the page actions menu by the title. |
| `LlmsTxt` | `LlmsTxtOptions?` | `null` | The options EnableLlmsTxt set. Null while it is off. |

```csharp
o.EnableLlmsTxt(l =>
{
    l.RulesFile = "Llms/agent-rules.md";
    l.InstallCommandPattern = @"dotnet add package MyLib\.\w+";
});
```

The options and the files are covered in [AI agents (llms.txt)](https://shelldocs.shellui.dev/docs/guides/llms-txt.md).

## Options that do nothing yet

`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](https://shelldocs.shellui.dev/docs/theming.md).

## This site's configuration

```csharp
builder.Services.AddShellDocs(o =>
{
    o.ContentRoot = Path.Combine(builder.Environment.ContentRootPath, "content");
    o.SiteName = "ShellDocs";
    o.SiteTagline = "The docs framework for .NET.";
    o.GitHubRepo = "shellui-dev/shelldocs";
    o.SiteUrl = "https://shelldocs.shellui.dev";
    o.LayoutVariant = DocsLayoutVariant.Sidebar;
    o.LogoSvg = File.ReadAllText(Path.Combine(builder.Environment.WebRootPath, "brand", "mark.svg"));

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

    o.EnableLlmsTxt(l =>
    {
        l.Summary = "ShellDocs is a docs framework for .NET: Markdown pages, live Blazor component previews, search and a static export, in a Blazor Web App.";
        l.RulesFile = "Llms/agent-rules.md";
        l.InstallCommandPattern = @"(?m)(?<=^[ \t]*)dotnet (?:tool install -g ShellDocs\.CLI|add package ShellDocs\.\w+)[^\r\n]*";
    });

    o.AddNavLink("Documentation", "/docs/introduction");
    o.AddNavLink("Releases", "https://github.com/shellui-dev/shelldocs/releases");

    o.AddPackage("shelldocs",            "ShellDocs",            "The framework.",        "/docs/introduction");
    o.AddPackage("shelldocs.components", "ShellDocs.Components", "Chrome and primitives.", "/docs/packages/components");
    o.AddPackage("shelldocs.markdown",   "ShellDocs.Markdown",   "The markdown pipeline.", "/docs/packages/markdown");
    o.AddPackage("shelldocs.cli",        "ShellDocs.CLI",        "The command line.",      "/docs/packages/cli");
});
```

## Next

- [Authoring](https://shelldocs.shellui.dev/docs/authoring.md): Write pages: frontmatter, code fences, live previews.
- [Component reference](https://shelldocs.shellui.dev/docs/components/callout.md): Every shipped primitive.
- [Documenting a component library](https://shelldocs.shellui.dev/docs/guides/component-libraries.md): Register and preview your own components.
- [Deployment](https://shelldocs.shellui.dev/docs/guides/deployment.md): Static export or a .NET host.
- [AI agents (llms.txt)](https://shelldocs.shellui.dev/docs/guides/llms-txt.md): Docs that coding agents can read.