Hub templates and the page catalog

​

One artifact, three registries

​

What a hub template is

​

Name interpolation

​

Playlists and placeholder documents

{
  "title": "Getting Started",
  "key": "getting-started",
  "visibility": "public",
  "file_ids": [],
  "documents": [
    {
      "title": "Add your first lesson",
      "description": "This is a placeholder lesson — open it in the editor and swap it for your first real one.\n\n## Three ways to add content\n\n- **Upload a video or audio file** …"
    }
  ]
}

• title — the playlist’s display title.
• key — a template-scoped handle, unique within the template. It exists so other parts of the same template can reference the playlist before it has an id (see binding); it is not stored on the created hub.
• visibility — public, unlisted, or private. This flows to playlist creation; note that a private playlist’s detail page is unreachable for members, so shipped templates use public.
• file_ids — ids of existing media files to attach. Usually empty: a template cannot reference media that doesn’t exist until the hub does.
• documents[] — placeholder text documents, described next.

​

How documents materialise

​

The description does triple duty

1. The lesson body — a document file with no media renders its description as the lesson text, markdown included.
2. The read-time estimate — the “N min read” chip on the card is computed from it.
3. The card blurb — the starter homepage’s Getting Started band renders each document as a card, and that card binds the document’s description into a dedicated field (node id gs-card-description in the catalog artifact), clamped to two lines. The field is optional: a document with no description renders no blurb rather than an error.

​

Binding pages to seeded playlists

{ "dataSource": { "type": "playlist", "id": "", "key": "getting-started" } }

​

Anatomy of a recipe

• A recipe node has a kind, settings, and either a children array or a literal value — never both.
• Recipe ids are placeholders. Instantiating a recipe deep-clones it and mints a fresh UUIDv7 for every node, so ids in the catalog (root, hero, gs-card) are symbolic and never survive into a real page.
• Structural settings keys — slot, name, role — survive cloning, which is how a template can address its own nodes after ids are re-minted.
• Data-bound nodes additionally carry dataSource, repeat, collapseWhenEmpty, and binding settings such as valueFrom and actionFromScope.
• Templates can declare variants keyed by variant id (hero.playlist, row.3eq); instantiation picks the requested variant and falls back to starter.
• Recipes omit defaults rather than restating them. A setting a recipe leaves out defers to the renderer’s built-in default for that key — so don’t read the absence of a key as the absence of behavior.

​

Versioning and pinning

{
  "meta": {
    "schemaVersion": "2.1.0",
    "catalogVersion": "0.23.0",
    "revision": 40,
    "digest": "sha256:76ba947342356c25873d8852264fa0014340157080bdd21ef1e793732736a87b",
    "createdAt": "2026-07-14T00:00:00Z"
  }
}

• The version you fetch is a pin, not the newest catalog. The platform vendors a specific catalog release and bumps it deliberately, so the served artifact moves in steps. Trust the meta of the artifact you actually fetched; never assume it matches the catalog’s latest release.
• Cache by digest. Send If-None-Match: "<digest>" and handle 304 Not Modified; the response is cacheable for five minutes. When the digest changes, everything derived from the catalog — mirrored enums, scaffolded trees, generated docs — should be re-derived.
• The CLI carries its own pin. The offline verbs (mio pages catalog templates / section-types / scaffold) work against the CLI’s embedded, digest-pinned copy and need no network; mio hubs templates and mio hubs scaffold read the backend’s live catalog, so hub scaffolding always follows the backend’s pin. The two pins can differ between releases — when exactness matters, compare digests.

​

Where to go next

• Page-builder catalog — the generated reference: current version and digest, all templates, node kinds, and the full settings vocabulary.
• Pages and page builder — the node envelope, draft/publish contract, and the silent-drop render gotchas.
• Create a hub — the scaffold command this vocabulary feeds, plus the step-by-step manual recipe.