Site-wide documents

Not everything a site stores is a page. A navigation menu, a design-tokens document, a set of global contact details — these are site-wide documents: a known, small set of files with a schema, not a growing folder of pages. Authors shouldn't find them by spelunking the file browser, and nobody should ever "add a new one" from the new-page dialog.

Flag their collection with area: site and the editor does the right things:

• the collection surfaces in the sidebar's Content group, next to Pages and Media, instead of the Pages area,
• a single-document collection opens straight in the editor — one click from anywhere to "edit the design" or "edit the navigation",
• it's excluded from the "+ New page" picker, so authors can't accidentally mint a second settings file.

Everything else about the collection is ordinary: the same field types, validation, drafts, Publish, history, discussion, and live preview as any page.

Declaring one

A site-wide document is a collection like any other, plus area: site:

# .norcube/cms/collections/theme.yml
label: Design
description: Site-wide design — colors, font, corner roundness.
path: src/content/settings
match: 'theme.md' # literal filename → a single document
area: site
previewPath: '/'
fields:
  - key: colors
    type: group
    label: Colors
    fields:
      - key: accent
        type: color
        format: hex
        label: Accent
  # …

One document or several

The match glob decides the shape:

• Literal match (theme.md, globals.yml) — a single document. The sidebar entry opens it directly.
• Glob match ('*.md', '*.yml') — a small set of documents, e.g. per-language navigation files (cs.md, en.md). The sidebar entry opens the file browser scoped to the collection's path, and you pick the language from there.

Per-language site documents are worth calling out as a pattern: navigation labels differ per language, so "navigation" is naturally one document per locale, matched by a glob — while a design-tokens document is naturally one per site, matched by a literal filename. Both fit the same mechanism.

YAML data files

Site-wide documents don't have to be Markdown. A file ending in .yml or .yaml is treated as a whole-file data document:

• Reads: the entire file parses as the frontmatter — the editor shows the same field form it would for a Markdown head. There is no body.
• Writes: saves emit pure YAML. No --- fences, no trailing body — the file stays exactly what a framework data-loader expects.
• Everything downstream works the same: the identity sidecar, per-field history, the History tab's schema-aware diff, and live-preview sync.

# src/content/navigation/en.yml — the whole file is the "frontmatter"
main:
  - label: Services
    page: services
  - label: Contact
    page: contact

Use .yml when the consuming framework reads data files directly (Astro data collections, Eleventy _data, …) and frontmatter-only .md when your content loader only globs Markdown.

Creating the documents

Site-wide documents are deliberately not creatable from the editor — they're part of the site's contract, like the schema itself. Commit them once alongside the collection file (a starter template typically ships them), and from then on authors only ever edit them.

Recipes

Design tokens

Keep the whole visual identity — colors, font choice, corner radius, spacing density — as a single document, built from color, range and select fields. Your build turns the document into CSS custom properties (a small generate-on-change step in dev makes the live preview restyle itself as the author drags a slider). Pair with previewPath: '/' so the preview shows the homepage recoloring in real time.

Navigation, per language

One document per locale, glob-matched ('*.md' or '*.yml'), each holding main: and footer: link lists. An item references a page by its translation key (your build resolves the URL from the page's slug) or carries a direct href for external links. Adding a language to the site is adding one file.

Global variables

A single document holding site-wide {{placeholder}} values — phone number, company ID, address. This one gets first-class editor support (an insert-at-cursor dropdown and resolved-value hints); it has its own page.

Where to next