Website als Code: Struktur und Inhalte als Dateien pflegen
Collections, Blöcke, Komponenten, Layouts, Theme, Seiten, Menüs, Formulare und Einträge als Dateien im Repository führen und mit hcms pull, diff und push abgleichen – in der richtigen Reihenfolge.
Worum es geht
Alles, was Sie in Sites in der Oberfläche anlegen, lässt sich auch als Datei im Git-Repository Ihrer Website führen. Die Kommandozeile hcms gleicht diese Dateien mit Sites ab. Vorteile: Änderungen sind nachvollziehbar und prüfbar (Pull Request), lassen sich zwischen Umgebungen wiederholen, und KI-Werkzeuge können eine ganze Website als Dateien aufbauen.
Üblich ist eine Arbeitsteilung: Die Struktur (Collections, Blöcke, Layouts, Theme) entsteht als Code, die redaktionellen Inhalte pflegt die Redaktion in der Oberfläche.
Voraussetzungen
- Ein Projekt mit
hcms.config.json, siehe Eigene Website anbinden. - Ein Token mit der Berechtigung Verwaltung; für Einträge zusätzlich Schreiben und Veröffentlichen. Übergeben Sie es mit
--tokenoder alsHCMS_TOKEN.
Die drei Befehle je Ressource
| Befehl | Wirkung |
|---|---|
hcms <ressource> pull |
Stand aus Sites in Dateien schreiben (hcms pull ohne Ressource zieht alles auf einmal und schützt lokale Änderungen) |
hcms <ressource> diff |
Zeigen, was ein Push ändern würde (berechnet von Sites) |
hcms <ressource> push |
Dateien in Sites übernehmen; mit --dry-run nur anzeigen |
Ein Push ist:
- idempotent: Abgeglichen wird über einen festen Schlüssel (z.B.
slug), nicht über interne IDs. Zweimal pushen ändert beim zweiten Mal nichts. - ergänzend: Er legt an und aktualisiert, löscht aber nie. Was nur in Sites existiert, wird als „nur im Ziel vorhanden“ gemeldet. Entfernen Sie es bei Bedarf in der Oberfläche.
- versioniert: Jeder Push legt eine Version an.
Ressourcen und ihre Dateien
| Ressource | Befehl | Ordner (Standard) | $format |
Schlüssel |
|---|---|---|---|---|
| Collections | hcms schema |
cms/schema/collections/<slug>.json |
hcms/collection@1 |
slug |
| Feldgruppen | hcms schema |
cms/schema/components/<slug>.json |
hcms/component@1 |
slug |
| Blöcke | hcms blocks |
cms/blocks/<slug>.json |
hcms/block@1 |
slug |
| Komponenten | hcms komponenten |
cms/komponenten/<slug>.json |
hcms/block-component@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/<pfad>.<sprache>.json |
hcms/page@1 |
path und locale |
| Menüs | hcms menus |
cms/menus/<key>.json |
hcms/menu@1 |
key |
| Formulare | hcms forms |
cms/forms/<key>.json |
hcms/form@1 |
key |
| Einträge | hcms content |
cms/content/<slug>.json |
hcms/content@1 |
syncKey und locale |
Seiten-Dateinamen bilden den Pfad ab: / wird zu index, Schrägstriche in verschachtelten Pfaden zu __. Beispiele: cms/pages/index.de.json, cms/pages/blog__mein-beitrag.de.json.
Beispiel: eine Collection
{
"$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" }
]
}Beispiel: eine Seite
{
"$format": "hcms/page@1",
"path": "/ueber-uns",
"locale": "de",
"title": "Über uns",
"status": "published",
"isVisible": true,
"seo": { "metaTitle": "Über uns" },
"blocks": [
{ "id": "b1", "type": "hero", "data": { "title": "Willkommen" } }
]
}Wird der Pfad geändert, entsteht beim nächsten Push eine neue Seite; die alte bleibt bestehen.
Beispiel: ein Menü mit Untermenü
{
"$format": "hcms/menu@1",
"key": "main",
"name": "Hauptmenü",
"items": [
{ "label": "Start", "type": "page", "pagePath": "/", "target": "_self", "isVisible": true },
{
"label": "Angebot", "type": "page", "pagePath": "/angebot", "isVisible": true,
"children": [
{ "label": "Beratung", "type": "page", "pagePath": "/angebot/beratung", "isVisible": true }
]
},
{ "label": "Blog", "type": "collection", "collectionSlug": "post", "isVisible": true }
]
}Untermenüs sind eine Ebene tief möglich. Ein menus push ersetzt alle Einträge des Menüs durch die Einträge der Datei – seit Version 0.12 als Entwurf, wie das Speichern in der Oberfläche. Live geht das Menü erst mit Veröffentlichen in Scorebase oder direkt mit hcms menus push --veroeffentlichen. menus pull zieht den neuesten Stand, auch einen offenen Entwurf.
Wichtig: Untermenüs legen Sie als Datei an; die Oberfläche zeigt sie eingerückt und behält sie beim Speichern, bietet aber keinen Knopf, um einen Eintrag unter einen anderen zu hängen.
Die Reihenfolge beim Push
Ressourcen verweisen aufeinander, und Sites prüft diese Verweise. hcms push erledigt alles in der richtigen Reihenfolge; hcms diff zeigt vorher, was es ändern würde (dasselbe wie hcms push --dry-run).
hcms diff # Probelauf über alle Stufen
hcms push # schema → theme → blocks → komponenten → layouts → menus → pages → forms| Stufe | Inhalt |
|---|---|
1. schema |
Collections und Feldgruppen |
2. theme |
Theme |
3. blocks |
Block-Definitionen |
4. komponenten |
Komponenten als Datei |
5. layouts |
Layouts – werden gegen die Blöcke geprüft |
6. menus |
Menüs |
7. pages |
Seiten – Blöcke und Verweise werden geprüft |
8. menus noch einmal |
nur wenn dabei neue Seiten entstanden sind, damit Menüeinträge auf sie greifen |
9. forms |
Formulare |
Merksatz: schema → theme → blocks → komponenten → layouts → menus → pages → forms. Einträge (hcms content push --collection <slug>) gehören nicht dazu; pushen Sie sie danach einzeln.
- Stufen ohne Dateien überspringt
hcms push. - Beim ersten Fehler hält es an und nennt, was erledigt ist und was nicht mehr ausgeführt wurde. Nach der Korrektur starten Sie einfach neu: Ein Push ist idempotent.
--nur schema,blocksführt nur diese Stufen aus,--ohne formslässt Stufen weg. Unbekannte Namen lehnt der Befehl ab.--veroeffentlichenstellt alles live,--forceübergeht den Versionsschutz,--envwählt die Umgebung.- Im Probelauf prüft jede Stufe gegen den heutigen Stand der Umgebung. Neue Blöcke oder Komponenten aus früheren Stufen kennt sie noch nicht; Fehler wie „unbekannter Baustein“ können deshalb nur im Probelauf auftreten.
- Die Einzelbefehle (
hcms blocks pushund so weiter) gibt es weiterhin.
Kommt etwas in falscher Reihenfolge (z.B. ein Layout mit einem Block, den es noch nicht gibt), lehnt Sites es mit 422 VALIDATION_ERROR ab. Nicht auflösbare Verweise (z.B. ein Menüeintrag auf eine fehlende Seite) sind dagegen nur Warnungen; das betroffene Feld bleibt leer.
Ein layouts push speichert geänderte Layouts als Entwurf, wie das Speichern in der Oberfläche: Neue Seiten entstehen weiter aus der veröffentlichten Version, bis jemand in Scorebase Veröffentlichen klickt. Mit hcms layouts push --veroeffentlichen gehen sie sofort live. Ein neuer Slug legt das Layout an; es ist sofort veröffentlicht. layouts pull zieht den neuesten Stand, auch einen offenen Entwurf.
Komponenten als Datei
Eine Komponente ist ein wiederverwendbarer Baum aus Blöcken mit Eigenschaften und Varianten. Neben dem Komponenten-Builder können Sie sie als Datei cms/komponenten/<slug>.json führen. Die Datei hat dasselbe Format wie in Sites: eine Hülle ($format, slug, version, pflege) und die Definition darunter.
{
"$schema": "../.hcms/komponente.schema.json",
"$format": "hcms/block-component@1",
"slug": "hinweis-knopf",
"name": "Hinweis mit Knopf",
"version": 3,
"pflege": "beide",
"verwendbarIn": "beide",
"eigenschaften": [
{ "key": "text", "type": "text", "label": "Hinweistext", "default": "Die Anmeldung ist geöffnet." }
],
"baum": { "id": "root", "type": "basisText", "data": {} }
}| Befehl | Wirkung |
|---|---|
hcms komponenten pull [slug …] |
Neuesten Stand (auch einen offenen Entwurf) in Dateien schreiben; lokal geänderte Dateien bleiben unangetastet |
hcms komponenten diff [slug …] |
Zeigen, was ein Push ändern würde |
hcms komponenten push [slug …] |
Als Entwurf speichern; mit --veroeffentlichen sofort live |
- Editor-Hilfe:
hcms types generateschreibtkomponente.schema.json(undblock.schema.json) neben die erzeugten Typen. Der Verweis$schemain der Datei lässt Ihren Editor Schlüssel vorschlagen und Fehler anzeigen. - Entwurf und Veröffentlichen: Ein Push legt einen Entwurf an. Die Live-Version bleibt, bis jemand in Scorebase Veröffentlichen klickt oder Sie
--veroeffentlichenangeben. - Gleichzeitig geändert:
versionist der Stand, den Sie zuletzt gezogen oder gepusht haben. Hat jemand die Komponente seitdem in Scorebase geändert, stoppt der Push mit409 VERSION_CONFLICT, bevor er etwas schreibt. Ziehen Sie neu und führen Sie die Änderungen zusammen, oder überschreiben Sie bewusst mit--force. Nach einem Push trägt die CLI die neueversionin die Datei ein, ohne sie umzuformatieren. - Pflege:
"pflege": "beide"(Vorgabe) heisst, Code und Builder ändern dieselbe Komponente."pflege": "code"(„Nur im Code“) schützt sie im Builder vor Änderungen. Fehlt der Schlüssel, bleibt der Stand auf dem Server. - Prüfung: Jeder Push prüft Aufbau, Eigenschaften, Stile und verschachtelte Komponenten. Findet er etwas, wird nichts gespeichert (
422); die Meldung nennt Datei und Zeile. - Erst testen: Probieren Sie Änderungen in einer eigenen Umgebung aus und übernehmen Sie sie mit
hcms promote(siehe Umgebungen). - Auf der Website: Die Delivery-API liefert Komponenten ausgebreitet als gewöhnliche Blöcke. Mit
?components=rawbleiben die Instanzen erhalten; die Management-API liefert immer die Rohform.
Einträge synchronisieren
hcms content pull --collection post --out cms/content/post.json
hcms content push --collection postEinträge werden über syncKey und locale abgeglichen und in Paketen zu 100 übertragen. Beziehungen zwischen Einträgen schreiben Sie portabel als "$ref:<syncKey>"; hcms löst sie beim Push auf. Der syncKey bleibt beim Klonen und Übertragen zwischen Umgebungen gleich – so findet Sites denselben Eintrag in jeder Umgebung wieder.
Typen und KI-Dokumentation aktuell halten
Nach jeder Änderung an Collections oder Blöcken:
hcms types generate # cms/types.generated.ts neu erzeugen
hcms docs pull # cms/llms-full.txt neu ladenTypischer erster Durchlauf
export HCMS_TOKEN="hcms_live_…" # Berechtigung Verwaltung
hcms diff # Probelauf über alle Stufen
hcms push # alles in der richtigen Reihenfolge
hcms content push --collection <slug> # Einträge je Collection, einzeln
hcms types generate --scaffold-blocksWenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
422 VALIDATION_ERROR mit unbekanntem Feldtyp |
Tippfehler im Feldtyp | Gültige Typen siehe Collections und Felder |
422 beim Layout oder bei Seiten: unbekannter Block |
Blöcke noch nicht gepusht | hcms push verwenden oder zuerst hcms blocks push |
409 VERSION_CONFLICT bei einer Komponente |
Jemand hat sie seit Ihrem letzten Pull in Scorebase geändert | hcms komponenten pull, Änderungen zusammenführen; nur bewusst --force |
409 VERSION_CONFLICT bei hcms forms push („Im CMS geändert seit Ihrem letzten Pull“) |
Das Formular wurde seit Ihrem letzten Pull in Scorebase geändert | hcms pull (oder hcms forms pull), Datei abgleichen, erneut pushen; nur bewusst --force |
hcms pull nennt „lokal geändert, nicht überschrieben“ |
Die Datei weicht vom zuletzt gezogenen Stand ab | Änderung zuerst pushen oder sichern; nur bewusst hcms pull --force |
| Etwas wurde in Sites gelöscht und taucht nach dem Push wieder auf | Die Datei liegt noch im Repository | Datei löschen – Push löscht nie, legt aber an, was in Dateien steht |
| Push landet in der falschen Umgebung | --env fehlt und environment in hcms.config.json zeigt woanders hin, oder das Token ist an eine Umgebung gebunden |
--env angeben, Token prüfen |
403 FORBIDDEN |
Token ohne Verwaltung | Token mit Berechtigung Verwaltung verwenden |