Ich benutze Notion seit Jahren als redaktionelles Gehirn: Ideen, Recherchen, Briefings und sogar fertige Texte liegen dort. Gleichzeitig wollte ich weg von komplexen CMS hin zu einem schnellen, sicheren Static-Workflow. In diesem Artikel erkläre ich, wie ich Notion-Daten automatisiert in eine statische Website mit Eleventy umwandle und per GitHub Actions zu Netlify deploaye – vollständig automatisiert.

Warum Notion -> Static?

Notion ist großartig für Content-Erstellung und Teamarbeit. Aber Notion ist kein spezialisiertes Publishing-Tool: SEO, Performance und vollständige Kontrolle über HTML/CSS sind dort eingeschränkt. Eine statische Seite bringt mir:

  • Performance & Sicherheit (keine dynamischen Server).
  • Einfaches Versioning via Git.
  • Flexible Template- und Layout-Kontrolle mit Eleventy.
  • Automatische Deploys bei Content-Änderungen.

Architektur: Kurzüberblick

Meine Pipeline besteht aus folgenden Komponenten:

  • Notion als Schreib- und Redaktions-Backend.
  • Ein kleiner Exporter (Node-Script), der Notion-Inhalte zieht und in Markdown/Frontmatter umwandelt.
  • Eleventy (.eleventy) als Static Site Generator.
  • GitHub als Repository und Auslöser für CI.
  • GitHub Actions für Build und Deploy.
  • Netlify als Hosting und CDN (alternativ Vercel).

Was du vorbereiten musst

  • Ein Notion-Account und eine Database/Seite, die als Content-Quelle dient.
  • Notion Integration Token (Secret) - du findest/erstellt es in Notion unter Integrations.
  • Ein GitHub-Repository für deine Website.
  • Ein Netlify-Konto und ein Site-Token für Deployments (falls du Netlify CLI in Actions nutzt).
  • Grundkenntnisse in Node.js, Eleventy und GitHub Actions sind hilfreich.

Wie ich Notion-Inhalte exportiere

Ich nutze ein kleines Node-Script, das die offizielle Notion-API abfragt, Seiten analysiert und als Markdown mit Frontmatter speichert. Die Frontmatter enthält Titel, Datum, Tags, Slug und ggf. Metadaten für Social-Preview.

Wesentliche Punkte:

  • Verwende die Notion API Library (official notion-client) für stabile Abfragen.
  • Mappe Notion-Properties der Database auf YAML-Frontmatter-Felder.
  • Konvertiere Notion-Blocks (Paragraph, Heading, Bulleted List, Code, Image) in Markdown. Für komplexe Blöcke kannst du remark/Rehype oder eigene Mapper nutzen.
  • Lade Bilder herunter (oder setze externe URLs in Frontmatter), damit der Build deterministisch ist.

Ein minimaler Ablauf im Script:

  • Authentifizieren mit NOTION_TOKEN.
  • Query auf deine Database-ID – rufe alle Pages ab, die veröffentlicht sind.
  • Für jede Page: hole Blocks, mappe zu Markdown, generiere Frontmatter, schreibe content/posts/slug.md.

Eleventy konfigurieren

Ich nutze Eleventy, weil es leichtgewichtig ist und viel Kontrolle bietet. Meine wichtigsten Einstellungen:

  • Input: content/ (Markdown-Dateien aus Notion)
  • Layouts: _layouts/ mit Nunjucks oder Liquid
  • Shortcodes für Bilder und Social-Previews
  • Collections für Posts, Tags und Autoren

Beispiele für collection-Setup in .eleventy.js (Kurzbeschreibung):

  • addCollection('posts', ...) filtert nach Frontmatter.published und sortiert nach date.
  • addFilter('formatDate', ...) für konsistente Datumsausgabe.

GitHub Actions: Trigger & Workflow

Ich möchte, dass Änderungen in Notion automatisch einen Deploy auslösen. Zwei Strategien:

  • Periodic Pull: GitHub Action scheduled cron job, das Notion-Exporter-Script läuft, committed die generierten Markdown-Dateien zurück ins Repo. Dieser Commit löst dann einen Build + Deploy aus.
  • Webhook-ähnlicher Trigger: Statt direkten Webhooks von Notion (nicht nativ vorhanden), nutze ich einen externen Service (z. B. n8n oder Make), der regelmäßig Notion prüft und bei Änderungen eine GitHub Action Dispatch auslöst.

Meine bevorzugte Variante ist die erste: ein scheduled workflow, der alle 10 Minuten laufen kann (oder je nach Bedarf).

Wichtige Secrets in GitHub repo settings:

  • NOTION_TOKEN
  • NOTION_DATABASE_ID
  • GIT_COMMITTER_NAME / EMAIL (optional)
  • NETLIFY_AUTH_TOKEN (oder NETLIFY_SITE_ID, wenn du Netlify Deploy API nutzt)

Beispiel-Workflow (Beschreibung)

Der Workflow macht in Kurzform:

  • Checkout Repo
  • Set up Node.js
  • Install dependencies
  • Run notion-exporter script → schreibt Markdown-Dateien ins Repo
  • Wenn Dateien geändert: commit + push
  • Run Eleventy build
  • Deploy to Netlify (netlify-cli deploy oder Netlify Action)

Datei-Handling und Konflikte

Wenn der Export nach Markdown committet, müssen Konflikte sauber behandelt werden. Tipps aus meiner Praxis:

  • Arbeite mit einem deterministischen Export: gleiche Slugs, konsistente Dateibenennung (z. B. YYYY-MM-DD-slug.md).
  • Bevor du commitest, prüfe git status; in Actions kannst du mit einem diff prüfen, ob Änderungen vorhanden sind.
  • Falls mehrere Autoren parallel in Notion arbeiten, ist es sinnvoll, den Export häufiger laufen zu lassen und Merge-Konflikte durch präzise Slugs zu minimieren.

SEO, Bilder und Social Previews

Wichtig für Veröffentlichungen:

  • Erzeuge in Frontmatter Felder für meta-title, meta-description, og:image.
  • Für Bilder ziehe ich die Dateiversionen lokal oder speichere sie in einem CDN (z. B. Netlify Large Media oder ein S3-Bucket).
  • Automatisiere das Generieren von OpenGraph-Images (z. B. mit Puppeteer oder cloudinary), wenn du konsistente Social-Previews möchtest.

Vor- und Nachteile auf einen Blick

Vorteile Nachteile
Performance, Sicherheit, volle Kontrolle Erster Aufbau erfordert etwas Scripting
Automatisierte Deploys & Versioning Keine native Notion-Publishing-Funktionen (z. B. Comments auf Website)
Einfaches Rollback über Git Image-Handling und komplexe Notion-Blocks brauchen Mapping

Praktische Tipps aus meinen Projekten

  • Starte klein: exportiere zuerst nur Basis-Text & Headings, erweitere dann um Tabellen, Embeds und Code-Snippets.
  • Versioniere das Export-Script im Repo, so ist jede Änderung reproduzierbar.
  • Nutze netlify.toml für Build-Settings und Redirects – sehr praktisch für RSS oder alte Slugs.
  • Schütze deine Notion-Token als GitHub Secrets, teile sie nie im Klartext.
  • Teste den Workflow lokal mit act oder indem du das Script manuell ausführst, bevor du es in Actions automatisierst.

Wenn du möchtest, kann ich dir das Export-Script beispielhaft zuschicken (Node.js + notion-client + unified/remark) oder eine Boilerplate für Eleventy mit GitHub Actions und Netlify bereitstellen. Sag mir kurz, welche Notion-Struktur du hast (eine Database mit Properties: Titel, Datum, Tags?) und ich schicke eine angepasste Vorlage.