> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# holydocs new

Scaffold a new documentation page with frontmatter and a starter template.

## Usage

```bash
holydocs new <page-path> [options]
```

Creates a new MDX documentation page at the specified path with pre-populated frontmatter and a basic content template. The command handles directory creation, title derivation, and reminds you to add the page to your navigation.

## Arguments

| Argument | Description | Required |
|---|---|---|
| `<page-path>` | File path for the new page (relative to project root) | Yes |

The path can be provided with or without the `.mdx` extension. Nested paths automatically create intermediate directories.

## Options

| Option | Description | Default |
|---|---|---|
| `--title <title>` | Page title (used in frontmatter and heading) | Derived from path |
| `--dir <path>` | Root directory of the docs project | Auto-detected |

## Examples

### Create a Simple Page

```bash
holydocs new quickstart
```

Creates `quickstart.mdx`:

```mdx
---
title: "Quickstart"
description: ""
---

# Quickstart

Start writing your documentation here.
```

Output:

```
✓ Created quickstart.mdx

Don't forget to add it to your docs.json navigation:
  "quickstart"
```

### Create a Nested Page

```bash
holydocs new guides/authentication
```

Creates the `guides/` directory if it does not exist and writes `guides/authentication.mdx`:

```mdx
---
title: "Authentication"
description: ""
---

# Authentication

Start writing your documentation here.
```

### Specify a Custom Title

```bash
holydocs new api/rate-limiting --title "Rate Limiting & Quotas"
```

Creates `api/rate-limiting.mdx`:

```mdx
---
title: "Rate Limiting & Quotas"
description: ""
---

# Rate Limiting & Quotas

Start writing your documentation here.
```

### Deeply Nested Pages

```bash
holydocs new guides/advanced/custom-components
```

Creates all intermediate directories and writes `guides/advanced/custom-components.mdx`. The title is derived from the last path segment: "Custom Components".

## Title Derivation

When `--title` is not provided, the title is derived from the last segment of the page path:

| Page Path | Derived Title |
|---|---|
| `quickstart` | Quickstart |
| `guides/getting-started` | Getting Started |
| `api-reference/list-users` | List Users |
| `advanced/custom-mdx-components` | Custom Mdx Components |

The derivation converts hyphens to spaces and capitalizes the first letter of each word.

For titles with special formatting (acronyms, ampersands, or mixed case), use the `--title` flag to set the exact title you want.

## Duplicate Prevention

If a file already exists at the target path, the command exits with an error instead of overwriting:

```bash
holydocs new quickstart
```

```
Error: File already exists: quickstart.mdx
```

This prevents accidental overwrites of existing content. To recreate a page, delete the existing file first.

## Adding to Navigation

After creating a page, add it to the `navigation.groups` array in your `docs.json`:

```json
{
  "navigation": {
    "groups": [
      {
        "group": "Guides",
        "pages": [
          "guides/getting-started",
          "guides/authentication"
        ]
      }
    ]
  }
}
```

Pages that are not listed in `docs.json` navigation will not appear in the sidebar. They are still accessible by direct URL, but users will have no way to discover them through navigation.

## Batch Page Creation

Create multiple pages in sequence for a new documentation section:

```bash
holydocs new sdks/overview --title "SDK Overview"
holydocs new sdks/javascript --title "JavaScript SDK"
holydocs new sdks/python --title "Python SDK"
holydocs new sdks/go --title "Go SDK"
```

Then add all four pages to a single navigation group in `docs.json`.

## Related

- [holydocs init](/cli/init) -- Initialize a full project with template pages
- [holydocs check](/cli/check) -- Validate that new pages are referenced in navigation
- [holydocs dev](/cli/dev) -- Preview pages locally as you write