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

# Initialize Your CMS

> First-time setup for the Hiveku CMS — scaffold the manifest, get a default blog collection, and confirm everything's wired up

If your project doesn't have a `hiveku.cms.json` file yet, the CMS panel can scaffold one for you with a single click. This guide walks through that first-time setup, what the scaffold creates, and how to customize it before you start adding entries.

<Info>
  You only need to initialize once per project. After that, adding new collections is a separate flow — see [Add a New Collection](/how-tos/add-collection).
</Info>

## What "Initialize" Does

When you click **Initialize CMS**, Hiveku:

1. Creates `hiveku.cms.json` at your project root
2. Adds a default `blog` collection with sensible fields
3. Creates the `content/blog/` directory
4. Writes one seed entry — `welcome.mdx` — so the collection isn't empty
5. Reloads the CMS panel pointing at the new collection

The whole thing takes a couple of seconds.

## Steps

<Steps>
  <Step title="Open your project in /v3">
    From the [dashboard](https://app.hiveku.com/dashboard), click the project you want to set up.
  </Step>

  <Step title="Switch the right pane to CMS">
    The right pane has three tabs at the top — Preview, Code, CMS. Click **CMS**.

    Since there's no manifest yet, you'll see an empty state with a description of what the CMS does and an **Initialize CMS** button.
  </Step>

  <Step title="Click Initialize CMS">
    A confirmation dialog summarizes what will be created:

    * `hiveku.cms.json` at the project root
    * `content/blog/` directory
    * One seed entry: `content/blog/welcome.mdx`

    Click **Create** to proceed.
  </Step>

  <Step title="Confirm the file appeared in the file tree">
    Switch the right pane to **Code** briefly. You should see `hiveku.cms.json` at the root and a `content/` folder containing `blog/welcome.mdx`. Switch back to **CMS** to keep working.
  </Step>

  <Step title="Inspect the default fields">
    The CMS panel now shows the `Blog Posts` collection with one entry (`welcome`). Click it to open the form.

    The default fields are:

    * **title** (string, required)
    * **publishedAt** (date)
    * **status** (select: draft / published)
    * **tags** (array of strings)
    * **body** (markdown, the post body)

    These are a sensible starting point for most blogs. You can change them at any time.
  </Step>

  <Step title="Edit the seed entry (optional)">
    The seed entry has placeholder content. Edit the title, body, and any other fields, then click **Save**. The preview updates with the new content.
  </Step>
</Steps>

## What the Scaffold Creates

The scaffold writes a manifest with a single collection. Here's the literal output:

```json theme={null}
{
  "version": 1,
  "collections": [
    {
      "id": "blog",
      "name": "Blog Posts",
      "path": "content/blog",
      "format": "mdx",
      "slugFrom": "filename",
      "fields": [
        { "name": "title", "type": "string", "required": true },
        { "name": "publishedAt", "type": "date" },
        { "name": "status", "type": "select", "options": ["draft", "published"], "default": "draft" },
        { "name": "tags", "type": "array", "items": "string" },
        { "name": "body", "type": "markdown", "isBody": true }
      ],
      "routePattern": "/blog/{slug}",
      "defaultSort": "publishedAt desc"
    }
  ],
  "webhooks": []
}
```

And the seed entry:

```mdx theme={null}
---
title: "Welcome to your CMS"
publishedAt: "2026-04-25"
status: "published"
tags: ["welcome"]
---

This is your first CMS entry. Edit me, or delete me and create a new one.

You can write Markdown here. Images, headings, lists, links — they all work.
```

## Customize Before Going Further

A few common tweaks people make right after initialization:

### Add an excerpt field

Useful for blog index pages that show a teaser per post:

```
Ask the AI: "Add an excerpt field (multiline string, max 280 chars) to the blog collection."
```

### Add an author reference

If your blog has multiple authors, create an `authors` collection and reference it from the blog:

```
Ask the AI: "Add an authors collection with name, bio, and avatar. Then add an
author reference field to the blog collection, required."
```

### Rename `body` to `content`

Personal preference — the field name shows up in MDX frontmatter for every entry, so make it match your style.

### Replace the default seed entry

If you don't want the placeholder welcome post, delete it from the entry list and create your real first post.

## Initializing Without the UI

You can also initialize from the AI chat:

```
Set up a CMS for this project. I want a blog collection and a separate
authors collection. Authors should have name, bio, avatar, and a Twitter
URL. Blog posts reference authors.
```

The AI will scaffold the manifest, create the directories, and (optionally) seed both collections — and may infer additional fields based on what your existing site looks like.

## Verifying the Setup

A quick checklist after initialization:

<AccordionGroup>
  <Accordion title="The CMS panel shows your collection">
    Open the right pane, set it to CMS mode. The collection picker should list `Blog Posts` (or whatever you set up).
  </Accordion>

  <Accordion title="The seed entry renders in preview">
    Click the welcome entry. The Live Preview should navigate to `/blog/welcome` and show the rendered post.

    If the preview shows a 404, your blog template hasn't been wired up to read the CMS yet. Ask the AI: *"My blog template at app/blog/\[slug]/page.tsx isn't reading from the CMS — fix it."*
  </Accordion>

  <Accordion title="A file appeared in the code editor">
    Switch to Code mode. You should see `hiveku.cms.json` at the root and `content/blog/welcome.mdx`.
  </Accordion>

  <Accordion title="The version history works">
    Edit the seed entry, save, then open the version history drawer. You should see the new save in the list — that confirms versioning is working.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Initialize button is disabled">
    A `hiveku.cms.json` already exists in the project. Open the code editor to confirm. If you want a fresh scaffold, delete the existing manifest first (or back it up to a different name).
  </Accordion>

  <Accordion title="Manifest validation error after init">
    Rare, but possible if your project has an unusual structure. Open `hiveku.cms.json` in the code editor and check for typos or invalid JSON. The error banner in the CMS panel points at the offending field.
  </Accordion>

  <Accordion title="Preview shows 404 for the seed entry">
    Your blog template doesn't exist yet, or doesn't read from the CMS. The scaffold creates the manifest and entry but doesn't generate React components — see *"My blog template isn't wired up"* in the AI chat for an automated fix.
  </Accordion>

  <Accordion title="I want to start over">
    Delete `hiveku.cms.json` and the `content/` directory from the code editor, then click **Initialize CMS** again.

    <Warning>
      Deleting the manifest and content directory removes all entries. If you have content you want to keep, snapshot the project first.
    </Warning>
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Add a Collection" icon="plus" href="/how-tos/add-collection">
    Add more collections beyond the default blog
  </Card>

  <Card title="Migrate a Site" icon="arrow-right-arrow-left" href="/how-tos/migrate-site-to-cms">
    Move hardcoded content into the CMS
  </Card>

  <Card title="Editing Content" icon="pencil" href="/cms/editing-content">
    Day-to-day use of the CMS panel
  </Card>

  <Card title="The Manifest" icon="file-code" href="/cms/manifest">
    Full reference for `hiveku.cms.json`
  </Card>
</CardGroup>