Sveltia CMS Einrichtungsleitfaden

7. Juni 2026 um 16:0028. Juli 2026 um 12:00by Gui

Technologie CMS Astro Cloudflare Sicherheit

Inhaltsverzeichnis

Wann Sveltia CMS passt
Gesamtarchitektur
1. Admin unter public/admin ablegen
2. GitHub Backend konfigurieren
3. OAuth Worker ergänzen
4. Medienordner früh festlegen
5. Collections trennen
6. relation und select verwenden
7. Japanische Source-JSONs editierbar machen
8. Writer-Zugang nur in Production bereitstellen
9. Mit dem Save-Proxy prüfen und direkt veröffentlichen
10. Übersetzung nur durch CMS-Commits auslösen
11. Eigenes CSP für /admin
Turnstile trennen
Lessons Learned aus PRs und Commits
Minimaler Startpunkt
Referenzen
Fazit

Sveltia CMS ist nützlich, wenn eine statische Website eine Editieroberfläche erhalten soll, ohne Inhalte in eine externe Datenbank zu verschieben. Dieser Leitfaden beschreibt den Einbau in die Acecore-Astro-Website und die Korrekturen, die sich später aus echten PRs und Commits ergeben haben.

Aktualisiert am 28. Juli 2026: CMS-Saves werden jetzt nach synchroner Prüfung direkt als einzelner cms:-Commit nach main geschrieben. GitHub OAuth prüft Editor und aktuelle Schreibberechtigung; eine nur für acecore-net installierte GitHub App führt Repository-Zugriffe aus. JSON-/Markdown-Schema, Bildsignatur, aktive HTML/URLs und erwarteter HEAD werden vor dem Schreiben geprüft.

Der Titel ist bewusst schlicht: Sveltia CMS Einrichtungsleitfaden. Es geht nicht um einen allgemeinen CMS-Vergleich, sondern um eine übertragbare Umsetzung.

Wann Sveltia CMS passt

Sveltia CMS besitzt keine eigene Inhaltsdatenbank und stellt keine separate Content-API bereit. Es ist eine SPA im Browser, die Dateien im Repository über das GitHub Backend bearbeitet.

Es passt gut, wenn:

Inhalte als Markdown oder JSON im Repository liegen
Änderungen an Artikeln, Autoren, Tags und Seitentexten als Git-Diffs reviewbar bleiben sollen
keine zusätzliche Datenbank oder Admin-Anwendung eingeführt werden soll
Uploads unter public/uploads liegen können
CMS-Saves die Veröffentlichung sofort starten sollen, während Codeänderungen weiter per Pull Request geschützt bleiben

Für komplexe Rollen, große Mediatheken, umfangreiche Freigabeprozesse oder Echtzeitdaten ist ein vollständiges Headless CMS sinnvoller.

Gesamtarchitektur

public/admin/index.html
  -> lädt @sveltia/cms per CDN

public/admin/config.yml
  -> definiert GitHub Backend, Collections und Medienordner

workers/sveltia-cms-auth
  -> Cloudflare Worker für GitHub OAuth

main branch
  -> einzige Quelle für die Produktion

CMS save proxy
  -> validiert Pfade und Inhalte und schreibt einen expected-HEAD cms:-Commit nach main

.github/workflows/create-translation-prs.yml
  -> erzeugt Übersetzungs-Tasks nur für cms:-Commits

Die Admin-Seite ist nur der Anfang. Authentifizierung, Medienpfade, Preview-Branches, Übersetzungen und Merge-Strategie gehören zur CMS-Architektur.

1. Admin unter `public/admin` ablegen

In Astro wird public unverändert statisch ausgeliefert. Auch die Sveltia-CMS-Dokumentation nennt public als Static-Folder für Astro, Next.js, Nuxt, Remix und VitePress.

<!doctype html>
<html lang="de">
  <head>
    <meta charset="utf-8" />
    <meta name="robots" content="noindex,nofollow" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CMS</title>
  </head>
  <body>
    <script src="https://unpkg.com/@sveltia/cms@0.172.4/dist/sveltia-cms.js"></script>
  </body>
</html>

Zusätzliche CSS-Dateien oder type="module" sind nicht nötig. Die UI-Styles stecken im JavaScript-Bundle.

Acecore nutzt manuelle Initialisierung für explizite Backend-Konfiguration. Der Veröffentlichungsbranch bleibt in jeder Umgebung main.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

2. GitHub Backend konfigurieren

Minimal braucht man backend.name und backend.repo. Für den Betrieb sollten Branch, OAuth und Commit-Messages ebenfalls feststehen.

backend:
  name: github
  repo: owner/repository
  branch: main
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql
  auth_methods: [oauth]
  commit_messages:
    create: 'cms: create {{collection}} "{{slug}}"'
    update: 'cms: update {{collection}} "{{slug}}"'
    delete: 'cms: delete {{collection}} "{{slug}}"'
    uploadMedia: 'cms: upload "{{path}}"'
    deleteMedia: 'cms: delete media "{{path}}"'

main bleibt der Veröffentlichungsbranch. Reads und Saves laufen über einen Same-Origin-Proxy. Vor jedem Save prüft er die aktuelle Schreibberechtigung des GitHub-Users, verwendet für Repository-Zugriffe eine nur in acecore-net installierte GitHub App und validiert Änderungspfade, Inhalte sowie den aktuellen main-HEAD, bevor er genau einen Direct Commit erstellt.

Mit Stand vom 20. Juli 2026 ist Editorial Workflow in Sveltia CMS nicht implementiert. Die Decap-CMS-Einstellung publish_mode: editorial_workflow lässt Sveltia CMS nicht automatisch kurzlebige Branches oder PRs erstellen.

Ein dauerhafter Branch wie cms-content erfordert laufende Synchronisierung und erhöht das Risiko für Konflikte oder eine falsche Deployment-Quelle. Acecore hält main als einzige Quelle der Wahrheit und lehnt konkurrierende Updates mit expectedHeadOid ab.

3. OAuth Worker ergänzen

Ein Personal Access Token reicht zum Testen, ist aber kein gutes Mehrbenutzer-Setup. Acecore verwendet Sveltia CMS Authenticator auf Cloudflare Workers und setzt dessen URL als base_url.

Der Callback der GitHub OAuth App zeigt auf /callback des Workers. Der Worker erhält GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET und optional ALLOWED_DOMAINS.

Das ist getrennt von Turnstile: OAuth schützt den CMS-Login, Turnstile schützt Formulare oder APIs gegen Bots.

4. Medienordner früh festlegen

Sveltia CMS speichert interne Medien im Repository. Für Astro ist diese Zuordnung praktikabel:

media_folder: public/uploads
public_folder: /uploads

Acecore hat diesen Punkt später in PR #116 korrigiert. Speicherpfad und öffentliche URL sollten direkt bei der CMS-Einführung gemeinsam festgelegt werden.

5. Collections trennen

collection	Ziel	Regel
`blog`	`src/content/blog/*.md`	Nur japanische Source-Artikel bearbeiten
`authors`	`src/content/authors/*.json`	Autorenprofile und lokalisierte Namen bearbeiten
`tags`	`src/content/tags/*.json`	Tags und lokalisierte Namen bearbeiten
page text	`src/i18n/source/ja/*/.json`	Japanische Source-Texte für Seiten und UI bearbeiten

Nicht alle übersetzten Markdown-Dateien müssen im CMS editierbar sein. Acecore behandelt Japanisch als kanonische Source und aktualisiert Übersetzungen über Mehrsprachige Blogs mit Sveltia CMS betreiben.

6. relation und select verwenden

Tags sollten über relation gewählt werden, nicht als Freitext.

- name: tags
  label: Tags
  widget: relation
  collection: tags
  value_field: name
  display_fields: ['{{name}} ({{id}})']
  search_fields: [name, id]
  multiple: true
  required: false

Dasselbe gilt für Autoren, Icons und Hinweisstile. Ein gutes CMS macht nicht nur Bearbeitung möglich, sondern verhindert kaputte Werte.

7. Japanische Source-JSONs editierbar machen

Feste Seitentexte lassen sich ebenfalls im CMS pflegen. Acecore bündelt sie unter src/i18n/source/ja/**/*.json.

Die Lehre: Nicht alle Felder auf einmal hinzufügen. config.yml wächst schnell. Besser mit Blog, Autoren, Tags, Hinweisen und häufig geänderten Seiten starten.

8. Writer-Zugang nur in Production bereitstellen

Client ID, Installation ID und Private Key der GitHub App werden nur in der Cloudflare-Pages-Production-Umgebung konfiguriert. Previews erhalten keine Writer-Zugangsdaten; Repository-Reads und -Writes bleiben dort deaktiviert. Inhalte werden ausschließlich über das Production-/admin/ gespeichert und veröffentlicht, während Pages-Previews normalen Code- und Konfigurations-PRs dienen.

CMS.init({
  config: {
    backend: {
      branch: 'main',
    },
  },
})

9. Mit dem Save-Proxy prüfen und direkt veröffentlichen

Ein Same-Origin-Save-Proxy prüft den erlaubten Umfang und den Inhalt synchron und erstellt genau einen Commit auf main.

backend:
  name: github
  repo: owner/repository
  branch: main
  api_root: /admin/api/github
  graphql_api_root: /admin/api/graphql

GitHub OAuth prüft direkt vor dem Save den Editor und dessen Schreibberechtigung. Ein kurzlebiges Installation-Token der nur für acecore-net installierten GitHub App übernimmt Repository-Lese- und Schreibzugriffe. Erlaubt sind nur freigegebene Inhalte und Bildformate; SVG und PDF werden abgewiesen.

Der Save verwendet den Start-HEAD als expectedHeadOid; konkurrierende Änderungen liefern 409. Bei verlorener GitHub-Antwort gilt der Save nur dann als erfolgreich, wenn Request-Marker, Parent-SHA, alle Pfade und Blob-SHAs übereinstimmen.

Der direkte Commit behält ein Subject wie cms: create ... oder cms: update .... Derselbe GitHub-App-Push startet Pages Deployment und Übersetzungs-Task. Code, Schema, Workflows, CMS-Konfiguration und Übersetzungsdateien bleiben PR- und CI-pflichtig.

10. Übersetzung nur durch CMS-Commits auslösen

PR #98 fügte --cms-only hinzu, damit Push-basierte Übersetzungs-Tasks nur auf CMS-Commits reagieren.

function isCmsCommitSubject(subject) {
  return /^cms: (create|update|delete) /.test(subject || '')
}

cms: ist ein Workflow-Vertrag, kein dekoratives Präfix.

11. Eigenes CSP für `/admin`

Die Admin-App verbindet sich mit CDN, GitHub API, OAuth Worker und blob URLs. Daher trennt Acecore die CSP für /admin/* und setzt diesen Bereich auf noindex.

Turnstile trennen

Die alte Fassung mischte CMS und Cloudflare Turnstile. Das war thematisch unscharf.

Sveltia CMS betrifft GitHub Backend, OAuth, Collections, Medien und PRs. Turnstile betrifft Bot-Schutz für Formulare oder APIs. Beides unterstützt sicheren Betrieb, liegt aber auf unterschiedlichen Ebenen.

Lessons Learned aus PRs und Commits

Wenn das CMS wechselt, müssen Artikel und interne Links mitziehen.
OAuth ist Teil des echten Setups, kein späteres Extra.
Medienpfade sollten vor den Uploads feststehen.
config.yml sollte schrittweise wachsen.
cms: ist ein Automatisierungsvertrag.
Writer-Zugangsdaten liegen nur in Production; Preview dient ohne Repository-Zugriff normalen Code- und Konfigurations-PRs.

Minimaler Startpunkt

public/admin/index.html
public/admin/config.yml
public/admin/init.js
public/admin/runtime-config.js

Danach folgen Autoren-Relationen, Tag-Relationen, Bilder, Source-JSONs, synchrone Direct-Publish-Prüfung und Übersetzungs-Tasks.

Referenzen

Fazit

Sveltia CMS lässt sich leicht unter public/admin ablegen. Für Produktion müssen aber Branch, OAuth, Medienordner, Source-Sprache, Übersetzungs-Workflow und Merge-Strategie geklärt sein. Dann bleibt eine Astro-Website statisch und leichtgewichtig, bekommt aber einen brauchbaren Inhaltsprozess.

Ablauf der Sveltia-CMS-Einrichtung

Admin-App, Authentifizierung, editierbare Inhalte, Medien und PR-Prozess sollten getrennt entworfen werden.

Admin-App hinzufügen

index.html und config.yml unter public/admin ablegen und Sveltia CMS laden.

GitHub konfigurieren

Repo, Branch, OAuth Worker und CMS-Commit-Messages vor der Nutzung festlegen.

Editierbaren Bereich begrenzen

Nur Blog, Autoren, Tags und japanische Source-JSONs als Collections freigeben.

Betrieb automatisieren

main als Veröffentlichungsbranch nutzen und validierte Direct Commits, Pages-Deployments und Übersetzungs-Tasks verbinden.

Vor und nach dem CMS

Markdown manuell bearbeiten

Aktualisierungen sind vor allem für GitHub- oder Editor-Nutzer einfach
Bildpfade, Autoren-IDs und Tags werden leicht falsch getippt
Japanische Source und Übersetzungen können vermischt werden
Speicherziel und beschreibbare Pfade können unklar sein

Bearbeitung mit Sveltia CMS

Markdown und JSON lassen sich im Browserformular bearbeiten
relation, image und select reduzieren ungültige Werte
Nur CMS-Commits lösen Übersetzungs-Tasks aus
Ein Same-Origin-Proxy validiert erlaubte Inhalte und schreibt einen Direct Commit nach main

Einrichtungs-Checklist

Erledigt: Sveltia CMS aus public/admin/index.html laden
Erledigt: GitHub Backend und Collections in public/admin/config.yml definieren
Erledigt: OAuth Worker für mehrere Editoren verwenden
Erledigt: media_folder und public_folder mit Astros public-Verzeichnis abgleichen
Erledigt: Festlegen, wie CMS-Commits Übersetzung oder Veröffentlichung auslösen

Häufige Fragen

Für welche Websites eignet sich Sveltia CMS?

Für statische Websites, deren Markdown oder JSON im Repository liegt, etwa Astro, Hugo oder VitePress. Man ergänzt ein CMS ohne externe Datenbank.

Reicht ein GitHub Personal Access Token?

Zum Testen ja. Für mehrere oder nicht-technische Editoren ist ein OAuth Worker sicherer und leichter zu erklären.

Sollten alle Sprachen im CMS editierbar sein?

Für kleine Teams ist es sicherer, nur die japanische Source im CMS zu bearbeiten und Übersetzungen per PR zu aktualisieren.

TeilenX B!Zu Hatena Bookmark hinzufügen

Kommentare

Kommentare werden geladen...

Gui

CEO von Acecore. Steuert Geschäftssysteme, Web, Datenbanken und Infrastruktur, Qualität und KI-Einsatz von der Analyse geschäftlicher Probleme über Design und Einführung bis zur Verbesserung nach dem Launch. Baut auf praktischer C#/.NET-Kompetenz auf und berücksichtigt zugleich PHP/JavaScript, SQL Server/PostgreSQL/MySQL und Linux/Windows Server, um Anforderungen, Technologieauswahl, Qualitätsstandards und GitHub-basierte Entwicklungsabläufe als kohärenten Prozess zu gestalten. Integriert generative KI in Entwicklungs-, Prüfungs- und Informationsorganisationsprozesse, als praktische Grundlage, damit kleine Teams schneller und verlässlicher liefern können.

Geschäftsproblem-AnalyseTechnologieauswahlSystemdesignC#/.NETDatenbank-/InfrastrukturdesignGitHub-EntwicklungsbetriebGenerative KIKI-Workflow-DesignQualitätsdesignVor-Ort-Integration

Möchten Sie mehr über unsere Dienste erfahren?

Wir bieten umfassende Unterstützung für Systementwicklung, Webdesign, Serverbetrieb und Grafikdesign.

Dienste anzeigen Kostenlose Beratung

Sveltia CMS Einrichtungsleitfaden

Wann Sveltia CMS passt

Gesamtarchitektur

1. Admin unter `public/admin` ablegen

2. GitHub Backend konfigurieren

3. OAuth Worker ergänzen

4. Medienordner früh festlegen

5. Collections trennen

6. relation und select verwenden

7. Japanische Source-JSONs editierbar machen

8. Writer-Zugang nur in Production bereitstellen

9. Mit dem Save-Proxy prüfen und direkt veröffentlichen

10. Übersetzung nur durch CMS-Commits auslösen

11. Eigenes CSP für `/admin`

Turnstile trennen

Lessons Learned aus PRs und Commits

Minimaler Startpunkt

Referenzen

Fazit

Kommentare

Gui

Verwandte Artikel

KI fragen

Verwandte Inhalte

Sveltia CMS Einrichtungsleitfaden

Wann Sveltia CMS passt

Gesamtarchitektur

1. Admin unter public/admin ablegen

2. GitHub Backend konfigurieren

3. OAuth Worker ergänzen

4. Medienordner früh festlegen

5. Collections trennen

6. relation und select verwenden

7. Japanische Source-JSONs editierbar machen

8. Writer-Zugang nur in Production bereitstellen

9. Mit dem Save-Proxy prüfen und direkt veröffentlichen

10. Übersetzung nur durch CMS-Commits auslösen

11. Eigenes CSP für /admin

Turnstile trennen

Lessons Learned aus PRs und Commits

Minimaler Startpunkt

Referenzen

Fazit

Kommentare

Gui

Verwandte Artikel

1. Admin unter `public/admin` ablegen

11. Eigenes CSP für `/admin`