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

# blodemd new

Create a new blode.md documentation site.

Create a starter documentation directory with a `docs.json` configuration file and an `index.mdx` page.

```bash
blodemd new [directory]
```

Interactive `blodemd new` inspects the current directory first:

- If the current directory is empty, it scaffolds there and prompts for the project slug.
- If the current directory is not empty, it asks whether to create the docs in a subdirectory or scaffold the current directory.
- If prompts are skipped with `--yes` or in a non-interactive environment, it falls back to `docs/`.

## What it creates

If you create the docs in a `docs/` subdirectory, `blodemd new` generates the following file tree:

  - docs/
    - docs.json
    - index.mdx

### docs.json

The generated configuration uses the hosted Blode.md schema and a single "Getting Started" navigation group. The `slug` field comes from the slug prompt, `--slug`, or a derived default. The `name` field defaults to a title-cased display name based on that slug unless you pass `--display-name`.

```json title="docs/docs.json"
{
  "$schema": "https://blode.md/docs.json",
  "name": "My Project",
  "slug": "my-project",
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["index"]
      }
    ]
  }
}
```

### index.mdx

A minimal starter page with a title and placeholder content:

```mdx title="docs/index.mdx"
---
title: Welcome
---

Start writing your docs here.
```

## Starter template

Use the starter template when you want a richer first pass with repo hygiene files, agent instructions, and branding assets:

- `.gitignore`
- `favicon.svg`
- `README.md`
- `AGENTS.md`
- `CLAUDE.md`
- `logo/light.svg` and `logo/dark.svg`
- `images/hero-light.svg`, `images/hero-dark.svg`, and `images/checks-passed.svg`
- `quickstart.mdx`
- `development.mdx`

```bash title="Starter template"
blodemd new --template starter
```

`AGENTS.md` links to `CLAUDE.md` when the local filesystem supports symlinks. The default `blodemd new` output stays as the minimal two-file scaffold.

> [!INFO]
> The starter does not generate a `LICENSE` file. Choose a license explicitly if
>   the repo will be public or open source.

## Options

- `--slug <slug>` (type: string): Project slug written to docs.json. If omitted, interactive mode prompts and non-interactive mode derives it from the chosen location.
- `--name <slug>` (type: string): Deprecated alias for `--slug`.
- `--display-name <name>` (type: string): Display name written to docs.json `name`. Defaults to a title-cased version of the slug.
- `--template <name>` (type: string, default: "minimal"): Scaffold an alternate template. Use "starter" for repo hygiene, helper files, and branding assets.
- `--yes` (type: boolean, default: false): Accept defaults without prompting.

## Examples

```bash title="Default directory"
blodemd new
```

```bash title="Create docs/ explicitly"
blodemd new docs
```

```bash title="Scaffold the current directory"
blodemd new .
```

```bash title="Set the slug explicitly"
blodemd new --slug acme-docs
```

```bash title="Set slug and display name"
blodemd new --slug docs --display-name "Blode.md"
```

```bash title="Custom directory"
blodemd new my-docs
```

```bash title="Starter template"
blodemd new --template starter
```

> [!INFO]
> `blodemd new` stops with an error if the target directory already contains any
>   scaffolded files. It also refuses to scaffold into a non-empty directory
>   unless you confirm that interactively.

## Next steps

1. Review `docs.json` and change `slug` if you want a different deployment target or `{slug}.blode.md` subdomain. Change `name` if you want a different visible site title.
2. If you used the starter template, replace the generated helper files and brand assets with project-specific content.
3. Add more `.mdx` pages and update the `navigation` array.
4. Run `blodemd push` to deploy.