Core concepts

A handful of ideas explain almost everything about how Minamo behaves. Read this once and the rest of the documentation will make a lot more sense.

Four top-level folders

A site is a plain folder, structured like this:

Text
my-site/
  content/     <- everything a marketing manager touches
    pages/
    menus/
    drafts/
    redirects.json
    settings.json
  theme/       <- everything a developer touches
    layouts/
    sections/
    blocks/
    snippets/
    assets/
    root/
    templates/
    config/
  media/       <- uploaded images and video, never git-tracked
  vhost/       <- this site's own server config
    site.config.json
    package.json
    server.js

content/, theme/, and vhost/ are ordinary git-tracked files. media/ is deliberately excluded from git — binary uploads committed forever is unbounded repo bloat with no diffing benefit, so it’s backed up separately.

Content vs. theme

These are the two halves of a page, and keeping them separate is the whole point of the sections-and-blocks model:

  • Theme defines what kinds of components exist — a hero section, a button block — and how each one renders, as a Liquid template plus a JSON Schema describing its settings.
  • Content is instances of those components, with real values, arranged on a real page — “a hero section with this heading, followed by a button block linking here.”

A marketing manager arranges and fills in components a developer already built. Neither one needs to touch the other’s half to do their job.

Draft, publish, and preview

Every page can exist in one or both of two states:

  • Live (content/pages/…) — what the public site actually serves.
  • Draft (content/drafts/…) — work in progress, mirroring the same folder structure.

Editing a live page creates a draft copy. Saving writes the draft to disk after validation — cheap, frequent, no git commit. Publishing validates the draft again, copies it over the live file, deletes the draft, and creates exactly one git commit authored by the editor who published it. This is why autosave doesn’t clutter your history with hundreds of commits: only publishing does.

Preview is a third view, used by the admin’s editor: it overlays whatever is in drafts/ on top of content/, so you see exactly what publishing will produce — including a page that is not yet published at all.

Note

Setting a page to unpublished doesn’t delete it — it simply makes the public site 404 on that URL, exactly as if the file didn’t exist. The file, and its history, are untouched.

Git as a feature, not a safety net

Because every publish is a real commit, a site’s entire editorial history is ordinary git history: diffable, blameable, and revertible. The admin’s page history view reads this directly — no separate revisions database, nothing to keep in sync. You don’t need to know git to use this; see Page history & rollback.

Schema versioning

Every content file carries a schemaVersion field. When the shape of content changes, the CMS ships a migration rather than asking anyone to hand-edit old files: npm run upgrade brings existing content along automatically, and npm run push puts the upgrade live. See Pull, push & upgrading.

What’s next

If you’re setting up a new site, continue to Quick start. If you’re building the theme, jump to Theme structure. If you’re managing content day to day, go to Getting started with the admin.