Sveltia CMS Einrichtungsleitfaden

7. Juni 2026 um 16:00 7. Juni 2026 by 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. Preview muss den richtigen Branch lesen
9. PRs aus dem CMS-Branch erstellen
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.

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-Änderungen vor Produktion per Pull Request geprüft werden sollen

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

cms-content branch
  -> Branch, auf dem das CMS Änderungen speichert

.github/workflows/cms-content-pr.yml
  -> öffnet PR von cms-content 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/[email protected]/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, damit Preview-Branches zur Laufzeit gewechselt werden können.

CMS.init({
  config: {
    backend: {
      branch: window.ACECORE_CMS_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: cms-content
  base_url: https://your-sveltia-cms-auth-worker.example.workers.dev
  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}}"'

Für persönliche Websites kann main reichen. Für Unternehmens- oder mehrsprachige Websites ist ein eigener Branch wie cms-content besser reviewbar.

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. Preview muss den richtigen Branch lesen

Wenn ein CMS in einer Cloudflare-Pages-Preview weiterhin main liest, passt der Editor nicht zur Preview. Acecore erzeugt vor dem Build public/admin/runtime-config.js und injiziert den aktuellen Branch.

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

9. PRs aus dem CMS-Branch erstellen

Änderungen in cms-content zu speichern und PRs nach main zu öffnen, hält Inhalte reviewbar.

on:
  push:
    branches:
      - cms-content

Die Merge-Methode ist wichtig. Übersetzungs-Tasks hängen an Commit-Subjects wie cms: create .... Wenn Squash-Merge diese entfernt, kann Automatisierung den Source-Change übersehen. Für CMS-PRs sind Merge-Commit oder Rebase-Merge geeigneter.

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.
In Preview muss klar sein, welchen Branch das CMS liest.

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, CMS-PR-Automatisierung 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

cms-content-Branch, CMS-PRs und Übersetzungs-Tasks verbinden, ohne normalen Entwicklungsfluss zu vermischen.

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
Preview-Umgebungen können versehentlich main lesen

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
Runtime Config wechselt den CMS-Branch zwischen Preview und Produktion

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.

Teilen X 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, einschließlich Webdesign, Grafikdesign und IT-Bildung.

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. Preview muss den richtigen Branch lesen

9. PRs aus dem CMS-Branch erstellen

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

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. Preview muss den richtigen Branch lesen

9. PRs aus dem CMS-Branch erstellen

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`