> ## 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.

# Add a New Collection to Your CMS

> Three ways to add a collection to your Hiveku CMS — via AI, via the CMS panel's Collection Manager, or by editing the manifest directly

Once your CMS is initialized, you'll add collections as your site grows. Maybe you started with just a blog and now you need case studies, team members, or product listings. There are three paths — pick whichever matches the situation.

<CardGroup cols={3}>
  <Card title="Easiest" icon="wand-magic-sparkles">
    Ask the AI
  </Card>

  <Card title="Visual" icon="pencil">
    Collection Manager UI
  </Card>

  <Card title="For developers" icon="code">
    Edit `hiveku.cms.json`
  </Card>
</CardGroup>

## Option 1: Ask the AI

The fastest way for most additions, especially when you have a clear idea of the fields.

<Steps>
  <Step title="Open your project in /v3">
    From the [dashboard](https://app.hiveku.com/dashboard), open the project.
  </Step>

  <Step title="Open the AI chat">
    Click the **AI** tab in the left panel.
  </Step>

  <Step title="Describe the collection you want">
    Be specific about purpose and fields. The more detail, the less back-and-forth.

    ```
    Add a "case-studies" collection with title, client name, industry,
    summary (short), hero image, and a long-form body. Route them at
    /case-studies/{slug}.
    ```

    Or, if you're less sure:

    ```
    I need a collection for our team page. Each team member has a name,
    title, photo, short bio, and links to their socials.
    ```
  </Step>

  <Step title="Review the proposed schema">
    The AI returns a manifest entry — collection ID, fields, route pattern, default sort. Approve or revise:

    * *"Make `industry` a select with options: SaaS, Healthcare, Finance, Other"*
    * *"Add a `featured` boolean so we can promote a few"*
    * *"Use field-based slugs from the title instead of filename"*
  </Step>

  <Step title="Approve and save">
    Once you're happy, the AI updates `hiveku.cms.json`, creates the directory under `content/`, and (optionally) seeds it with one example entry.
  </Step>

  <Step title="Verify in the CMS panel">
    Switch the right pane to **CMS** mode. The collection picker now lists your new collection. Click it — the entry list and form are ready to use.
  </Step>
</Steps>

<Tip>
  Ask the AI to also wire up the page that renders this collection: *"After adding the case-studies collection, create app/case-studies/page.tsx (list view) and app/case-studies/\[slug]/page.tsx (detail view) reading from the CMS."*
</Tip>

## Option 2: Collection Manager UI

Use this when you want a visual builder and immediate validation feedback.

<Steps>
  <Step title="Open the CMS panel">
    In `/v3`, switch the right pane to **CMS** mode.
  </Step>

  <Step title="Open Collection Manager">
    Click the gear icon at the top of the panel — it's next to the collection picker.
  </Step>

  <Step title="Click + New Collection">
    A form appears with the collection's top-level properties:

    * **ID** — `case-studies` (lowercase, hyphenated, must be unique)
    * **Display name** — `Case Studies`
    * **Path** — `content/case-studies` (auto-filled from ID)
    * **Format** — `MDX` (with body) or `JSON` (structured only)
    * **Slug from** — Filename or a specific field
    * **Route pattern** — `/case-studies/{slug}` (optional)
  </Step>

  <Step title="Define the fields">
    Click **+ Add Field** for each one. For each field:

    * **Name** — camelCase identifier
    * **Type** — picked from a dropdown (string, number, image, etc.)
    * **Required** — toggle
    * **Default** — typed if relevant
    * **Type-specific options** — like `options` for select, `collection` for reference

    Drag the rows to reorder them — order in the manifest matches order in the form.
  </Step>

  <Step title="Save">
    Click **Create Collection**. The Collection Manager closes, the manifest is updated, and the new collection appears in the picker.
  </Step>

  <Step title="Add your first entry">
    Click **+ New Entry** in the entry list and start filling in the form.
  </Step>
</Steps>

## Option 3: Edit the Manifest Directly

For developers who want full control or are scripting setup.

<Steps>
  <Step title="Open hiveku.cms.json">
    Switch the right pane to **Code** and open `hiveku.cms.json` from the file tree.
  </Step>

  <Step title="Add a new entry to the collections array">
    Following the [manifest schema](/cms/manifest):

    ```json theme={null}
    {
      "id": "case-studies",
      "name": "Case Studies",
      "path": "content/case-studies",
      "format": "mdx",
      "slugFrom": "filename",
      "fields": [
        { "name": "title", "type": "string", "required": true },
        { "name": "client", "type": "string", "required": true },
        { "name": "industry", "type": "select", "options": ["SaaS", "Healthcare", "Finance", "Other"] },
        { "name": "summary", "type": "string", "multiline": true, "maxLength": 320 },
        { "name": "heroImage", "type": "image" },
        { "name": "publishedAt", "type": "date" },
        { "name": "body", "type": "markdown", "isBody": true }
      ],
      "routePattern": "/case-studies/{slug}",
      "defaultSort": "publishedAt desc"
    }
    ```

    Drop it inside the existing `collections` array.
  </Step>

  <Step title="Save the file">
    `Cmd+S` / `Ctrl+S`. The CMS panel reloads and validates the manifest. If anything is wrong (duplicate ID, invalid field type, missing isBody on MDX), you'll see an error banner.
  </Step>

  <Step title="Create the directory">
    The CMS panel creates the directory automatically when you save the first entry. If you want it created up front, add an empty `.gitkeep` file:

    Right-click `content/` → **New Folder** → `case-studies` → New File → `.gitkeep`
  </Step>

  <Step title="Add a sample entry">
    Either via the CMS panel (click **+ New Entry**) or by creating a file directly. For an MDX collection:

    Right-click `content/case-studies/` → **New File** → `acme-corp.mdx` and paste:

    ```mdx theme={null}
    ---
    title: "How Acme Corp doubled conversion"
    client: "Acme Corp"
    industry: "SaaS"
    summary: "We helped Acme rebuild their checkout flow..."
    publishedAt: "2026-04-01"
    ---

    The full case study goes here in Markdown.
    ```
  </Step>
</Steps>

## Verifying

After adding a collection through any path:

<Steps>
  <Step title="Check the collection picker">
    Open the CMS panel. The new collection should be in the picker.
  </Step>

  <Step title="Open the form for a new entry">
    Click **+ New Entry**. Every field you defined should render with the right control.
  </Step>

  <Step title="Save a real entry">
    Fill in the required fields and save. Confirm the file appears in the file tree at the expected path.
  </Step>

  <Step title="Render it">
    If you set a `routePattern`, navigate the preview to that URL. If you also asked the AI (or wrote yourself) a page that reads this collection, the entry should render. If not, ask the AI: *"Build the list and detail pages for the case-studies collection."*
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Manifest invalid after edit">
    The most common cause is a typo or duplicate `id`. The error banner in the CMS panel points at the offending collection. Fix in the code editor and save.
  </Accordion>

  <Accordion title="Slug conflict on save">
    Two entries with the same slug can't coexist in one collection. Rename one. If you're using `slugFrom: "field:title"`, picking a unique title resolves it.
  </Accordion>

  <Accordion title="`isBody` set on a JSON collection">
    Validation rejects this — body fields are only valid on MDX collections. Remove `isBody: true` from the field, or change the format to `mdx`.
  </Accordion>

  <Accordion title="Two `isBody: true` fields on one MDX collection">
    Exactly one body field is allowed per MDX collection. Remove `isBody: true` from one of them.
  </Accordion>

  <Accordion title="ID has uppercase or spaces">
    `id` must be lowercase, alphanumeric, and hyphenated. `Case Studies` is invalid; `case-studies` is correct. Display names can be any string — that's the `name` field.
  </Accordion>

  <Accordion title="Reference field's collection doesn't exist">
    A `reference` field's `collection` value must match an existing collection's `id`. Add the target collection first, or fix the reference.
  </Accordion>

  <Accordion title="The collection appears but the entry list is empty">
    Expected for a brand-new collection. Click **+ New Entry** to add the first one.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Field Types" icon="list" href="/cms/field-types">
    Pick the right type for each field
  </Card>

  <Card title="References" icon="link" href="/how-tos/cms-references">
    Link collections together
  </Card>

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

  <Card title="Migrate to CMS" icon="arrow-right-arrow-left" href="/how-tos/migrate-site-to-cms">
    Pull existing hardcoded content into your new collection
  </Card>
</CardGroup>