Code-first Authoring
Ressourcen als Dateien modellieren: natürliche Schlüssel, das Dateiformat und die verbindliche Push-Reihenfolge.
Ressourcen und ihre Dateien
Jede CMS-Ressource ist eine kanonische JSON-Datei mit einem $format-Marker und einem stabilen natürlichen Schlüssel, über den der Upsert erfolgt:
| Ressource | CLI | Verzeichnis (Standard) | $format |
Natürlicher Schlüssel |
|---|---|---|---|---|
| Sammlungen | hcms schema |
cms/schema/collections/<slug>.json |
hcms/collection@1 |
slug |
| Komponenten | hcms schema |
cms/schema/components/<slug>.json |
hcms/component@1 |
slug |
| Blöcke | hcms blocks |
cms/blocks/<slug>.json |
hcms/block@1 |
slug |
| Layouts | hcms layouts |
cms/layouts/<slug>.json |
hcms/layout@1 |
slug |
| Theme | hcms theme |
cms/schema/themes/<name>.json |
hcms/theme@1 |
name |
| Seiten | hcms pages |
cms/pages/<path>.<locale>.json |
hcms/page@1 |
path + locale |
| Menüs | hcms menus |
cms/menus/<key>.json |
hcms/menu@1 |
key |
| Einträge | hcms content |
cms/content/<slug>.json |
hcms/content@1 |
syncKey + locale |
| Formulare | hcms forms |
cms/forms/<key>.json |
– | key |
Buchungen und Webshop stehen nicht mehr in dieser Tabelle: sie liegen seit dem 22. September 2026 in der Termine- bzw. der E-Commerce-App. Siehe Formulare, Webshop und Buchungen.
Der Seiten-Dateiname bildet den Pfad ab: Root / wird zu index, verschachtelte Pfade nutzen __ statt /. Beispiel: cms/pages/index.de.json, cms/pages/blog__mein-post.de.json.
Beispiel: eine Sammlung
{
"$format": "hcms/collection@1",
"slug": "post",
"name": "Blogbeiträge",
"fields": [
{ "key": "title", "label": "Titel", "type": "text", "required": true },
{ "key": "slug", "label": "Slug", "type": "slug" },
{ "key": "cover", "label": "Titelbild", "type": "image" },
{ "key": "body", "label": "Inhalt", "type": "richtext" }
]
}Die verbindliche Push-Reihenfolge
Der Server validiert Referenzen und weist Ressourcen ab, die in falscher Reihenfolge kommen. Führen Sie zuerst immer einen diff/--dry-run aus und deployen Sie dann in dieser Reihenfolge:
hcms schema push # Sammlungen + Komponenten (definiert Felder)
hcms blocks push # Block-Definitionen
hcms layouts push # Layouts (Block-Baum wird gegen die Palette geprüft)
hcms theme push # Design-Tokens
hcms pages push # Seiten (Block-Baum + Referenzen)
hcms menus push # Menüs (Seiten-Links werden über den Pfad aufgelöst)
hcms content push --collection <slug> # je Sammlung mit EinträgenMerksatz: schema → blocks → layouts → theme → pages → menus → content.
Gründe: Layouts werden gegen die Block-Palette validiert (unbekannter Block-Typ → 422); Menüs lösen ihre Einträge über Seiten-Pfade auf. Ein menus push ersetzt alle Einträge des Menüs.
Einträge (Content) synchronisieren
Redaktionelle Einträge einer Sammlung werden gebündelt gepusht. Der natürliche Schlüssel ist syncKey (plus locale):
hcms content pull --collection post --out cms/content/post.json
hcms content push --collection postRelationen zwischen Einträgen werden portabel über "$ref:<syncKey>" referenziert und beim Push aufgelöst.
Dry-run und Diff
Vor jedem Deploy prüfen, was sich ändern würde:
hcms schema diff
hcms pages push --dry-run--dry-run schreibt nichts und gibt nur den Diff zurück. Nicht auflösbare Referenzen sind nicht-fatale Warnungen; gelöschte lokale Dateien werden nur gemeldet, nie im CMS entfernt.
Wichtig: Der Push ist immer additiv. Um etwas im CMS zu entfernen, nutzen Sie die CMS-UI – die CLI löscht nie.