shelldocs init

shelldocs init is the "get to running docs" command. Two modes: create (default) makes a fresh Blazor Web App under docs/<Name>.Docs/ and wires everything for you, attach (--attach) augments an existing Blazor project in place without touching its Program.cs.

Synopsis

shelldocs init [path] [--dir <dir>] [--attach] [--yes] [--theme <preset>]

Create mode (default)

Scaffolds a fresh Blazor Web App and patches the template to be a working ShellDocs site : one command from empty directory to a running docs project.

shelldocs init MyDocs

Produces MyDocs/ in the current directory (or, when called with no path, docs/<CwdName>.Docs/).

1. "> Scaffolds a fresh Blazor Web App using the standard template. Fails fast if the target directory exists and isn't empty : use --attach` instead of overwriting.

2. Adds package references

   Injects <PackageReference Include="ShellDocs.Components" /> and <PackageReference Include="ShellDocs.Tokens" /> into the freshly-created .csproj. Both pinned to the CLI's shipped version.

3. Adds content copy-to-output

   Inserts a <Content Update="content/**/*.md;content/**/meta.json" CopyToOutputDirectory="PreserveNewest" /> group so dotnet publish carries the markdown corpus into the publish output.

4. Writes starter content

   Creates content/docs/introduction.md and content/docs/meta.json : the minimum a ShellDocs site needs to render.

5. Writes `Components/Pages/DocsPage.razor`

   The single-page router that serves every /docs/** URL from the .md files under content/. You don't edit this : it's just a <DocsLayout> around a <MarkdownContent>.

6. Strips the fresh-template chrome

   Deletes Counter.razor, Weather.razor, NavMenu.razor, MainLayout.razor.css, Home.razor.css. Rewrites MainLayout.razor as a bare pass-through and replaces Home.razor with the ShellDocs welcome page.

7. Patches `Program.cs`

   Adds using ShellDocs.Components;, builder.WebHost.UseStaticWebAssets();, and builder.Services.AddShellDocs(...) : anchoring on the exact template shape produced by dotnet new blazor.

8. Patches `Components/App.razor`

   Adds the _content/ShellDocs.Tokens/tokens.css and component CSS links, the theme-bootstrap script, and shelldocs.js + Shiki loader. Also switches <Routes /> to <Routes @rendermode="InteractiveServer" /> so interactive components (theme toggle, search, tabs) come alive.

9. Registers with the nearest solution

   Walks up from the working directory looking for a .slnx or .sln (stops at the repo root or 6 levels up). If one is found and doesn't already reference the project, runs dotnet sln add.

Path inference

When called with no path argument, the target is docs/<CwdName>.Docs/. So running from ~/code/my-library/ produces ~/code/my-library/docs/my-library.Docs/.

Site name

The header brand is derived from the target directory name, stripping a trailing .Docs suffix. my-library.Docs → header shows "my-library".

GitHub prompt

Interactive mode asks for owner/repo (blank to skip). The answer wires the GitHub link in the header and is used by search / social meta. Pass --yes to skip the prompt.

Attach mode (--attach)

Augments an existing Blazor project in place. Never touches your Program.cs : instead emits SHELLDOCS_SETUP.md with copy-paste snippets so you can wire ShellDocs into your custom middleware, auth, or DI without a merge conflict.

shelldocs init --attach --dir path/to/my/blazor/project

1. Verifies the target is a Blazor project

   Checks the .csproj for Microsoft.NET.Sdk.Web, .Razor, .BlazorWebAssembly, or a Microsoft.AspNetCore.Components reference. Bails if none match.

2. Adds package references

   Same as create mode.

3. Writes starter content

   Same as create mode.

4. Writes DocsPage.razor

   Same as create mode.

5. Writes SHELLDOCS_SETUP.md

   A per-project setup guide with copy-paste snippets for the exact AddShellDocs, MapShellDocs, and App.razor additions your project needs. This is what create mode does automatically : attach mode leaves it to you.

Options

Exit codes

See also