Ich arbeite seit Jahren mit Notion für Content-Planung, Dokumentation und als einfache CMS-Alternative. Irgendwann kam der Punkt, an dem ich meine Inhalte versionieren, mit Branches arbeiten und automatisierte Deployments einführen wollte — ähnlich wie bei jeder anderen Website oder Dokumentation. In diesem Artikel beschreibe ich meinen praktischen Notion‑zu‑git‑Workflow: wie ich Inhalte aus Notion extrahiere, in Markdown verwandle, Branches abbildbar mache und Deployments per CI/CD automatisiere. Du bekommst konkrete Tools, Musterentscheidungen und Fallstricke aus meiner Praxis.
Warum Notion in git bringen?
Notion ist genial für Kollaboration und schnelles Schreiben. Aber es fehlt die native Versionskontrolle im Sinne von Branches, Pull Requests und Revisions-Historie, wie wir sie aus git kennen. Für mich waren die Hauptgründe, Notion-Inhalte in git zu bringen:
- Ich möchte Änderungen reviewen (PRs), bevor sie live gehen.
- Ich brauche Branches für Feature- oder Übersetzungs-Workflows.
- Automatisierte Deployments auf statische Sites oder Headless-CMS sollen möglich sein.
- Backup und Unabhängigkeit von einer proprietären Plattform.
Überblick meines Workflows
Kurz gefasst besteht mein Workflow aus diesen Schritten:
- Notion-Inhalte strukturieren (Datenbank/Pages mit klaren Metadaten)
- Export / Synchronisation aus Notion in Markdown
- Speichern in einem git-Repository mit Branching-Regeln
- CI/CD (z. B. GitHub Actions) für Build & Deployment
- Optional: Webhooks oder Automationstools für Echtzeit-Updates
Struktur in Notion: Basis für sauberen Export
Bevor du irgendetwas exportierst, lege in Notion eine konsistente Struktur an. Ich nutze eine Datenbank für Blog-Posts mit folgenden Properties:
- Title
- Slug (manuell oder per Template generiert)
- Status (draft, review, published)
- Branch (z. B. main, feature/xyz, translations/de)
- Publish date
- Tags / category
Die Property Branch ist für mich wichtig: sie bestimmt, in welchen git-Branch der Export landet. So kann ein Beitrag als feature/-Branch leben, bis ein PR gemergt wird.
Tools für den Export: Optionen & Empfehlungen
Es gibt mehrere Ansätze, Inhalte aus Notion zu bekommen. Ich habe zwei Strategien, die ich je nach Projekt wähle:
1. Direkt per Notion‑API + Custom Script
Vorteile: flexibel, transformiert Daten gezielt, kontrolliert Metadaten. Nachteile: Entwicklungsaufwand.
- Ich nutze die offizielle Notion API kombiniert mit einem Node.js-Skript, das die Datenbank abruft, Block-Strukturen in Markdown konvertiert und Frontmatter (YAML) ergänzt.
- Bibliotheken wie notion-client oder @notionhq/client sind hier hilfreich. Für die Markdown-Konvertierung setze ich auf notion-to-md oder eigene Renderer, wenn ich spezielle Embeds/Datentabellen brauche.
- Das Skript schreibt Dateien in den richtigen Ordner und legt sie in den Zielbranch (siehe weiter unten).
2. Tools & Integrationen (no/low-code)
Wenn ich weniger entwickeln möchte, verwende ich Tools wie:
- Make.com oder Zapier für einfache Exports
- n8n für flexible, selbst gehostete Automation
- Third‑party-Export-Tools (z. B. notion-exporter, notion2md), die Notion-Seiten in Markdown umwandeln
Diese Tools sind schnell eingerichtet, aber oft weniger flexibel beim Umgang mit komplexen Notion-Blöcken (Folds, Databases-Relationen, Embeds).
Branch‑Mapping: Wie ich Notion-Status auf git-Branches abbilden
Ein klares Branch‑Mapping hilft, Konflikte zu vermeiden. Das Schema, das sich bei mir bewährt hat:
| Notion Property "Branch" | Git-Branch |
| main / published | main |
| draft | drafts/ |
| review | review/ |
| translations/de | i18n/de/ |
Technisch setze ich das so um: das Export-Skript liest die Property Branch und pusht die Markdown-Datei in das entsprechende Remote-Branch. Bei Branch-Neuerstellung benutze ich GitHub API oder das lokale git-CLI im CI-Runner.
Beispiel: Export-Skript — Ablauf
- Authentifizieren gegen Notion API.
- Abfragen aller Items mit Status != published (oder gezielt per Filter).
- Konvertieren zu Markdown + Frontmatter (Titel, Datum, Tags, Slug).
- Für jeden Post: prüfen, ob Branch existiert → erstellen oder updaten.
- Commit & Push der Änderungen.
Das Skript läuft bei mir lokal, per Cron oder via CI (GitHub Actions) ausgelöst. Bei Änderung in Notion kann ein weiterer Trigger (z. B. Make.com webhook) das CI anstoßen.
CI/CD: Automatisches Build & Deployment
Für statische Sites verwende ich Hugo oder Eleventy und deploye auf Netlify oder Vercel. Der Flow:
- Push in branch → GitHub Actions startet
- Action baut die Site (install, build)
- Preview-Deploy für feature/review-Branches (Netlify/Vercel bieten Preview URLs)
- Merge in main → Produktions-Deploy
Preview-Deploys sind besonders wertvoll: Redakteure und Reviewer können Änderungen in einer live Preview prüfen, bevor sie mergen. Ich konfiguriere die CI so, dass preview-URLs per Kommentar im PR oder per Slack-Notification geteilt werden.
Konflikte und Merge‑Strategien
Conent-Merges sind komplizierter als Code-Merges. Meine Regeln:
- Für größere Änderungen: immer Feature-Branch + PR mit Review
- Für kleine Typo-Fixes: direkte Änderungen im main-Branch (wenn gewünscht)
- Automatische Konfliktauflösung nur bei trivialen Metadaten; bei Inhaltskonflikten manuell lösen
Ich filtere automatisch nach last-edited-by oder timestamps, um Konflikte aufzudecken. Git-PRs machen hier den Review-Prozess transparent.
Metadaten, Frontmatter und SEO
Beim Export achte ich darauf, vollständiges Frontmatter zu erzeugen: Title, slug, date, tags, draft: true/false, canonical URL, description. Das ermöglicht gleiches Verhalten wie bei einem klassischen Static-Site-Generator.
Ein Tipp: generiere das Slug-Feld in Notion automatisch via Template oder per Export-Skript aus dem Titel. Inkonsistente Slugs sind eine häufige Fehlerquelle.
Monitoring, Backups und Datenschutz
Ein Vorteil des git-Exports: backups sind trivial (git history + remote). Trotzdem:
- Behalte sensible Daten aus Notion aus den Exports heraus (z. B. interne Notizen)
- Für automatisierte Exports sichere Tokens in GitHub Secrets oder Vault
- Logging im Export-Skript hilft, fehlgeschlagene Exporte zu erkennen
Praktische Beispiele & Tools, die ich benutze
- notion‑to‑md / notion-client (Node.js) für den Export
- GitHub Actions für CI/CD
- Netlify / Vercel für Preview & Prod Deploys
- n8n / Make.com, wenn ich Webhooks oder weitere Integrationen brauche
- Optional: Contentful oder Sanity wenn das Projekt wächst und Struktur wichtiger wird
Fehler, die ich gemacht habe (und wie du sie vermeidest)
Ein paar persönliche Learnings:
- Ich habe anfangs alle Notion-Blocks roh exportiert — das ergibt Chaos in Markdown. Besser: nur bestimmte Block-Typen zulassen oder eigene Renderer bauen.
- Keine Branch-Strategie → viele Konflikte. Lege früh Regeln fest (wer erstellt branches, wie lange leben sie etc.).
- Secrets in Klartext im Repo abgelegt — das sollte nicht passieren. Nutze CI-Secrets/Env-Vars.
- Preview-Deploys ignoriert → Review-Prozess litt. Preview-URLs sind Gold wert.
Wann lohnt sich dieser Workflow (und wann nicht)?
Für kleine persönliche Blogs oder wenn du nur gelegentlich publizierst, ist der Aufwand möglicherweise zu hoch. Der Workflow zahlt sich aus, wenn du:
- regelmäßig Inhalte veröffentlichst
- ein Team mit Review-Workflows hast
- Versionierung, Backups und automatisierte Deploys wichtig sind
Wenn du hingegen ein reines Notion-Archiv brauchst, reicht der native Export.
Wenn du magst, kann ich ein Beispiel-Skript (Node.js) oder eine GitHub Actions-Workflowdatei posten, die genau meinen Ablauf automatisiert — sag mir kurz, welche Tools du bevorzugst (Hugo/Eleventy, Netlify/Vercel) und ob du lieber einen Self‑Hosted Runner oder GitHub Actions verwendest.