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

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

Prop	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;

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");

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

Redirects

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

Brand logo

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

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

Previews

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

AI agents

Prop	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).

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.

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");
});

Authoring

Write pages: frontmatter, code fences, live previews.

Component reference

Every shipped primitive.

Documenting a component library

Deployment

Static export or a .NET host.

AI agents (llms.txt)

Docs that coding agents can read.