Project structure

After shelldocs init MyDocs from a directory called foo, you'll get:

  • foo
    • docsscaffold root : everything ShellDocs touches lives here
      • MyDocs.Docsthe Blazor Web App
        • Components
          • App.razorHTML shell : tokens.css, theme bootstrap, Shiki loader
          • Routes.razorRouter : DefaultLayout=DocsLayout
          • Pages
            • Home.razorlanding / welcome page : edit into your marketing surface
            • DocsPage.razorcatch-all /docs/{*Path} : renders markdown
          • Layout
            • MainLayout.razorpass-through fallback (real layout is DocsLayout from the RCL)
        • contentall authored markdown lives here
          • docs
            • introduction.mdthe starter page
            • meta.jsonsidebar ordering (optional : files auto-appear without it)
        • Program.csAddShellDocs configuration lives here
        • MyDocs.Docs.csprojreferences ShellDocs.Components + ShellDocs.Tokens

The four surfaces you'll touch

content/docs/
Where your authoring lives. Every .md file becomes a page. Every subfolder becomes a sidebar section.
Program.cs
Site config: name, tagline, GitHub link, layout variant, nav links, package selector, brand logo.
Components/Pages/Home.razor
Your landing page. Ships as a welcome hero : edit into your product's marketing surface.
Components/App.razor
HTML shell. Rarely edited : but useful when you want custom favicons, analytics scripts, or extra token overrides.

What ShellDocs adds to your .csproj

Prop Type Default Description
ShellDocs.ComponentsRequired PackageReference — RCL with all the chrome + primitives.
ShellDocs.TokensRequired PackageReference — CSS variables : palette + spacing scale.
Content Update ItemGroup content/**/*.md;content/**/meta.json Ensures markdown gets copied on `dotnet publish` : otherwise deployed sites 404 every page.

Content routing

The catch-all page in Components/Pages/DocsPage.razor maps every URL under /docs/* to a markdown file:

Prop Type Default Description
/docs/introduction URL content/docs/introduction.md Top-level page
/docs/components/callout URL content/docs/components/callout.md Nested via subfolder
/docs/guides/getting-started URL content/docs/guides/getting-started.md Two-level nesting works recursively

meta.json : optional ordering control

Each folder in content/docs/ can have a meta.json that controls sidebar ordering:

json 
{
  "title": "Documentation",
  "pages": [
    "introduction",
    "---",
    { "title": "Getting Started", "pages": ["installation", "quick-start"] },
    "components"
  ]
}
meta.json controls order, not presence

Files you don't list in pages still appear in the sidebar : they get appended alphabetically after your explicit ordering. So you can drop a new .md in and it shows up without touching meta.json. Only edit meta.json when you want a specific position, divider, or grouped subsection.

Next

Configuration
The full `ShellDocsOptions` surface : logo, nav, packages, layout variant, registered components.
Authoring guide
Frontmatter, code fences, razor:preview, inline components.