# Quick start

> From zero to a working docs site in five minutes.

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

Assumes you've already run `dotnet tool install -g ShellDocs.CLI --prerelease`. If not, hop over to [Installation](https://shelldocs.shellui.dev/docs/getting-started/installation.md) first.

**1. Scaffold**

Pick a directory (empty or your existing repo), then:

```bash
shelldocs init MyDocs
```

Creates a new Blazor Web App under `docs/MyDocs.Docs/`, wires the ShellDocs packages, patches `Program.cs`, drops a starter `content/docs/introduction.md`. One command → running docs site.

Prefer to augment an existing Blazor project instead of scaffolding fresh? Use `--attach`:

```bash
shelldocs init --attach --dir path/to/your/blazor/project
```

Attach mode never patches your `Program.cs` (respects your custom middleware / auth) : it emits a `SHELLDOCS_SETUP.md` with copy-paste snippets instead.

**2. Run the dev server**

```bash
cd docs/MyDocs.Docs
shelldocs dev
```

Serves at http://localhost:5000 with hot reload on `.md`, `.razor`, and `.cs` changes.

Or, equivalently:

```bash
dotnet watch run
```

`shelldocs dev` is a thin wrapper : same underlying behavior, plus markdown-file watching baked in.

**3. Open the site**

Visit http://localhost:5000. You should see:

```text
Welcome page  # Home.razor : customize this into your marketing page
/docs/introduction  # the starter page ShellDocs scaffolded for you
```

The sidebar auto-populates from your `content/docs/` folder. The Introduction page renders your starter markdown with a live `<Callout>` component and syntax-highlighted code.

**4. Add a new page**

```bash
shelldocs add component Button
```

Creates `content/docs/components/button.md` with frontmatter, a `razor:preview` skeleton, and an empty `<TypeTable>` for props documentation. Reload the browser : the page appears in the sidebar automatically. No `meta.json` edit required.

Other templates:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `component {Name}` | `template` |  | content/docs/components/{slug}.md : razor:preview + Props table + Notes |
| `guide {slug}` | `template` |  | content/docs/guides/{slug}.md : intro + Steps skeleton + Next section |
| `page {slug}` | `template` |  | content/docs/{slug}.md : blank frontmatter + H1 |

**5. Publish to static hosting**

```bash
shelldocs build --output publish
```

Prerenders every page into `publish/` as static files. Upload the folder to any static host. See [Deployment](https://shelldocs.shellui.dev/docs/guides/deployment.md) for a GitHub Pages workflow and for what needs a server instead.

## What just happened

You now have a Blazor Web App with:

- **File-based routing** : drop a `.md` in `content/docs/`, it becomes a page
- **Auto sidebar** : the tree structure of `content/docs/` becomes the nav
- **Live components** : `razor:preview` fences render real Blazor components inline
- **Search** : `Cmd+K` opens the search dialog, on a .NET host and on a static export alike
- **Dark mode** : theme toggle in the sidebar footer

## Next

- [Project structure](https://shelldocs.shellui.dev/docs/getting-started/project-structure.md): Understand what's in the folders shelldocs init created.
- [Authoring guide](https://shelldocs.shellui.dev/docs/authoring.md): Frontmatter, code fences, razor:preview, inline components.