Getting started

This walkthrough takes you from a fresh GitHub repo to publishing a first page through the editor. You should have:

• A GitHub repo for your site (any framework — Astro, SvelteKit, Hugo, Eleventy, Next, etc).
• A Norcube account + organisation.
• Owner / admin access on the repo (you need to install the Norcube GitHub App).

1. Create the site

In the Norcube dashboard, pick CMS → Create site. Give it a name + slug and pick the GitHub repo + branch you want the CMS to edit. The CMS will install the Norcube CMS GitHub App on the repo (it asks for contents: read+write and pull_requests: read+write, scoped to the repos you pick).

The CMS clones the repo to its working volume on first read — subsequent reads are sub-millisecond local-disk hits.

2. Bootstrap the schema

The CMS reads its config from .norcube/cms/config.yml in your repo. From CMS → Schema, click Initialise — the CMS commits a minimal config.yml to your branch:

# .norcube/cms/config.yml
schemaVersion: 1
publicDir: public

collections: []

publicDir is the directory your build serves static files from (Astro's public/, Hugo's static/, Next.js's public/, etc). The asset resolver maps leading-slash paths (/favicon.png) against it.

3. Declare your first collection

Add a directory under .norcube/cms/collections/ to describe a content type. For a blog the file is pages.yml:

# .norcube/cms/collections/pages.yml
label: Pages
path: src/content/pages # where your content files live
match: '**/*.md' # which files are part of this collection
fields:
  - key: title
    type: text
    label: Title
    required: true
  - key: description
    type: paragraph
    label: Description
    recommendedLength: { min: 50, max: 160 }
  - key: publishedAt
    type: date
    label: Published at
  - key: hero
    type: image
    label: Hero image
    storage: uploads
  - key: blocks
    type: array
    label: Content blocks
    items:
      - $ref: hero-compact
      - $ref: media-text

The CMS picks up the file on next config read (the page-editor preloads it). Authors can now open any matching content file and edit through the structured UI.

The $ref: entries point at per-block files under .norcube/cms/blocks/. Create them too:

# .norcube/cms/blocks/hero-compact.yml
label: Hero compact
fields:
  - key: heading
    type: text
    label: Heading
  - key: subheading
    type: paragraph
    label: Subheading

4. Declare a storage

If you have image / file fields, declare where their uploads go. Add to config.yml:

storages:
  uploads:
    type: repo
    path: public/uploads
    publicUrl: /uploads
    accept: image/*, application/pdf
    max_size: 10485760
    naming: slug+hash
    dedup: hash

defaultStorage: uploads

See Media library for the full storage knob list.

5. Add a content file

Either author one in the editor (CMS → Pages → New) or commit one directly:

---
title: Hello world
description: First page edited through Norcube CMS.
publishedAt: 2026-06-23
hero: /uploads/hero-c4f8b2a1.jpg
blocks:
  - _type: hero-compact
    heading: Welcome
    subheading: This page was edited through the CMS.
---

Body content goes here, in Markdown. Rich-text fields go in frontmatter;
the body is the page's main content surface.

The CMS reads, displays, and lets the author edit every frontmatter field via the schema-driven UI. The body renders in a Tiptap-based rich-text editor.

6. Publish → it's a commit

The editor has two distinct buttons:

• Save persists your in-progress edits as a draft. Local to the editor; no git operation. Auto-saves continuously as you type, and the Save button flushes the pending changes on demand.
• Publish commits the working copy to your branch with a subject like Norcube: edit src/content/pages/hello-world.md. CI / Cloudflare Pages / Vercel / wherever you deploy picks it up like any other commit.

In short: Save = local draft, Publish = git commit. Drafts can be abandoned by closing the editor without publishing; once published, the change is in git history and behaves like any other commit.

What you get out of the box

Once a site is wired up, every page in it inherits:

• Version history — every commit that ever touched the page, with schema-aware diff and three rollback flavours.
• AI Assistant — a chat sidebar that proposes edits as structured ops the author can review before applying.
• Discussion — per-page comment threads (separate from the git log).
• Activity feed — what's been happening on the site lately.
• Errors panel — schema-aware validation surfaced inline.

Where to next