RustyCMS: file-based headless CMS — API, Admin UI (content, types, assets), Docker/Caddy, image transform; only demo type and demo content in version control

Made-with: Cursor

docs/content-from-file.md

@@ -0,0 +1,27 @@
+# Content aus externer Datei (Typ `textOrRef`)
+
+Felder vom Typ **`textOrRef`** können entweder den Text direkt enthalten oder eine **Dateireferenz** im Format `file:pfad`. So bleibt das JSON klein und der Inhalt liegt in einer normalen Datei (z. B. `.md`).
+
+## Konvention
+
+- **Im JSON** steht entweder:
+  - der **Text direkt** (inline), oder
+  - eine **Referenz** `file:dateiname` (z. B. `file:markdown-stellungnahme-guide.content.md`), relativ zum Entry-Verzeichnis.
+- **Beim Lesen:** Ist der Wert eine `file:`-Referenz, lädt der Store den Inhalt aus der angegebenen Datei und liefert ihn als Feldwert. Ohne Referenz: liegt neben der Entry-Datei eine **`{slug}.content.md`**, wird deren Inhalt verwendet (Fallback).
+- **Beim Schreiben:** Wird inline-Text gespeichert, schreibt der Store ihn in `{slug}.content.md` und speichert im JSON nur noch `file:{slug}.content.md`.
+
+## Vorteile
+
+- Markdown/HTML in normalen Dateien bearbeiten, ohne Escaping im JSON.
+- Der **Pfad steht explizit im JSON** – klar erkennbar, wo der Inhalt herkommt.
+- Tooling (Editor, Linter, Git-Diffs) funktioniert zuverlässig.
+
+## Beispiel (Markdown-Collection)
+
+```
+content/de/markdown/
+  markdown-stellungnahme-guide.json5      # content: "file:markdown-stellungnahme-guide.content.md"
+  markdown-stellungnahme-guide.content.md # der eigentliche Markdown-Text
+```
+
+Die Auflösung gilt für alle Collections, sobald ein Feld den Typ `textOrRef` hat (z. B. `content` bei Markdown).