# `shelldocs add`

> Scaffold a starter .md page from a template into content/.

Source: https://shelldocs.shellui.dev/docs/cli/add

`shelldocs add` drops a starter `.md` page into your `content/` tree. Three templates, each pre-populated with the primitives you'd typically reach for : so you're editing content immediately instead of copy-pasting boilerplate.

## Synopsis

```bash
shelldocs add <template> <name> [--dir <dir>] [--force]
```

## Templates

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `component` | `template` |  | Starter page for a UI primitive. Preloaded with a razor:preview fence and a TypeTable skeleton. Goes to content/docs/components/{slug}.md. |
| `guide` | `template` |  | Starter walk-through. Preloaded with a Steps skeleton. Goes to content/docs/guides/{slug}.md. |
| `page` | `template` |  | Blank page : just frontmatter and an H1. Goes to content/docs/{slug}.md. |

## Examples

```bash
shelldocs add component MyBigCard      # → content/docs/components/my-big-card.md
shelldocs add guide getting-started    # → content/docs/guides/getting-started.md
shelldocs add page faq                 # → content/docs/faq.md
```

## Name → slug conversion

The `<name>` argument is slugified before it becomes a filename : PascalCase gets kebab-cased, spaces and underscores collapse to `-`, non-alphanumerics drop out.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `MyBigCard` | `→` |  | my-big-card.md |
| `getting-started` | `→` |  | getting-started.md |
| `Getting Started` | `→` |  | getting-started.md |
| `FAQ_v2` | `→` |  | faq-v2.md |

The frontmatter `title` uses a display-friendly variant:

- `component` template preserves PascalCase (`MyBigCard` → title `"MyBigCard"`, because that's how you'd tag it in a `razor:preview`).
- `guide` and `page` title-case with spaces (`getting-started` → title `"Getting Started"`).

## Overwriting

By default, `add` refuses to overwrite an existing file : `--force` lets it through.

```bash
shelldocs add page faq --force   # replaces content/docs/faq.md
```

## Options

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `template` (required) | `argument` |  | One of component, guide, page. |
| `name` (required) | `argument` |  | Page name. PascalCase for components, kebab / spaces / snake accepted for guides & pages. |
| `--dir` | `string` | `cwd` | Project directory. add looks for content/ under this path. |
| `--force` | `bool` | `false` | Overwrite an existing file with the same slug. |

## Exit codes

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `0` | `ok` |  | Page written. |
| `1` | `usage` |  | Missing arguments, unknown template, no content/ directory found, or file exists without --force. |

## Skipping the CLI

Nothing about ShellDocs requires `shelldocs add` : the framework's nav-graph builder discovers any `.md` file dropped into `content/**` automatically. Use `add` for a nice starting template; drop a blank file if you'd rather write from scratch.

## See also

- [Authoring](https://shelldocs.shellui.dev/docs/authoring.md): How to write pages : frontmatter, fenced code, inline components.
- [shelldocs dev](https://shelldocs.shellui.dev/docs/cli/dev.md): Run the site with hot-reload so your new page appears immediately.