# Project structure

> What ShellDocs scaffolds, and what each folder does.

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

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

```text
foo/
  docs/  # scaffold root : everything ShellDocs touches lives here
    MyDocs.Docs/  # the Blazor Web App
      Components/
        App.razor  # HTML shell : tokens.css, theme bootstrap, Shiki loader
        Routes.razor  # Router : DefaultLayout=DocsLayout
        Pages/
          Home.razor  # landing / welcome page : edit into your marketing surface
          DocsPage.razor  # catch-all /docs/{*Path} : renders markdown
        Layout/
          MainLayout.razor  # pass-through fallback (real layout is DocsLayout from the RCL)
      content/  # all authored markdown lives here
        docs/
          introduction.md  # the starter page
          meta.json  # sidebar ordering (optional : files auto-appear without it)
      Program.cs  # AddShellDocs configuration lives here
      MyDocs.Docs.csproj  # references 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`

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `ShellDocs.Components` (required) | `PackageReference` |  | RCL with all the chrome + primitives. |
| `ShellDocs.Tokens` (required) | `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:

| Name | 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](https://shelldocs.shellui.dev/docs/getting-started/configuration.md): The full ShellDocsOptions surface : logo, nav, packages, layout variant, registered components.
- [Authoring guide](https://shelldocs.shellui.dev/docs/authoring.md): Frontmatter, code fences, razor:preview, inline components.