Ich zeige dir, wie ich Notion‑Inhalte automatisch in statische Blogposts verwandle und per Git‑CI (GitHub Actions) mit Eleventy (11ty) deploye. Dieser Workflow hat mir geholfen, meine Inhalte in Notion weiterhin komfortabel zu schreiben und gleichzeitig eine performante, sichere statische Seite unter https://www.crest-datei.de zu betreiben. Im Folgenden beschreibe ich meine Architektur, die wichtigsten Schritte, typische Stolperfallen und konkrete Hinweise zu Templates, Frontmatter und GitHub Actions.

Warum Notion → statische Seite?

Notion ist hervorragend zum Schreiben, Strukturieren und Zusammenarbeiten. Für ein Blog möchte ich aber: schnelle Ladezeiten, einfache Deploys, SEO‑freundliche Seiten und volle Kontrolle über die Build‑Pipeline. Die Kombination aus Notion als Content‑Editor und Eleventy als Static Site Generator verbindet das Beste aus beiden Welten: komfortable Content‑Erstellung und robustes Deployment.

Übersicht des Workflows

Das ist die grobe Reihenfolge, die bei mir läuft:

  • In Notion schreibe ich Artikel in einer Datenbank.
  • Ein Node‑Script liest die Notion API aus, konvertiert Blocks in Markdown und erzeugt Frontmatter.
  • Die generierten Markdown‑Dateien landen im Repository (oder einem Content‑Branch).
  • GitHub Actions baut die Seite mit Eleventy und deployed (z. B. GitHub Pages, Netlify oder Vercel).

    • Auf diese Weise bleibt Notion die zentrale Quelle der Wahrheit (single source of truth).

    Notion API: Zugriff und Datenmodell

    Ich nutze die offizielle Notion API. Wichtig ist:

  • Erstelle einen Integrations‑Token in Notion und teile ihn mit der Ziel‑Datenbank.
  • Die Notion‑Datenbank sollte Felder wie Title, Slug, Published, Tags und Date haben.

    • Mit diesen Properties fülle ich später das Frontmatter. Ein häufiger Fehler ist, auf komplexe Block‑Typen zu vertrauen (Embeds, Toggles, Callouts). Ich beschränke mich auf Text, Überschriften, Bilder und einfachen Code, weil die Markdown‑Konvertierung sonst sehr viel komplexer wird.

    Markdown‑Konvertierung und Frontmatter

    Ich verwende ein kleines Node‑Script (z. B. notion2md oder eine eigene Implementierung), das Notion‑Blocks in Markdown umwandelt und ein YAML‑Frontmatter voranstellt. Das Frontmatter sieht bei mir typischerweise so aus:

    Frontmatter‑Beispiel (in YAML)

    ---
    title: "Mein Notion Artikel"
    date: "2026-02-01"
    slug: "notion-zu-eleventy"
    tags: ["Notion","Eleventy"]
    published: true
    ---

    Praktische Tipps:

  • Achte auf ein konsistentes Slug‑Feld. Wenn keines vorhanden ist, generiere eines automatisch aus dem Title (z. B. lowercased, spaces → hyphens).
  • Wenn du Bilder in Notion verwendest, lade sie idealerweise extern hoch (z. B. in ein CDN) oder speichere sie in einem /assets‑Ordner im Repo und passe die Bildpfade im Markdown an.
  • Konvertiere Code‑Blöcke mit Sprache, damit Eleventy Syntax‑Highlighting machen kann.

    • Eleventy (11ty) Setup

    Mein Eleventy‑Projekt hat diese Struktur:

  • /_includes – Templates und Partials
  • /posts – generierte Markdown‑Dateien aus Notion
  • /assets – Bilder, CSS, JS
  • /.eleventy.js – Konfiguration

    • Wichtige Punkte bei der Eleventy‑Konfiguration:

  • Permalink‑Vorlage: benutze das Frontmatter‑Slug, z. B. permalink: "/blog/{{ slug }}/index.html".
  • Taxonomien für Tags: Ein kurzes Plugin oder eigene Filter, um Tag‑Listen und Tag‑Seiten zu erzeugen.
  • RSS/JSON‑Feeds: Generiere einen Feed aus den veröffentlichten Posts (published: true).

    • GitHub Actions: CI Pipeline

    Meine GitHub Actions Pipeline macht drei Dinge: zieht Content, baut die Seite, deployed. Grober Workflow:

  • Trigger: push auf main oder ein Zeit‑Schedule (z. B. täglich) und optional ein manueller Dispatch.
  • Step 1 – Fetch Content: Ein Job ruft die Notion API ab und committet die generierten Markdown‑Dateien in einen Branch (z. B. content oder zurück in main).
  • Step 2 – Build: Eleventy baut die Seite.
  • Step 3 – Deploy: Deploy auf GitHub Pages, Netlify oder ein S3/CloudFront Setup.

    • Wichtiges YAML‑Snippet (konzeptionell):

    Wichtig: Setze Secrets in GitHub (NOTION_TOKEN, GITHUB_TOKEN, NETLIFY_TOKEN etc.).

    Atomic Commits vs. Pull Requests

    Ich habe zwei Varianten ausprobiert:

  • Automatischer Commit in main: schnell, aber kann ungewollte Commits erzeugen und CI‑Trigger mehrfach auslösen.
  • Commit in separaten Content‑Branch + PR: sicherer. Du siehst die Änderungen, kannst sie prüfen und manuell mergen.

    • Für meinen Blog habe ich mich für den Content‑Branch + automatischen Merge nach Review entschieden. Das verhindert, dass Drafts versehentlich live gehen.

    Handling von Assets (Bilder, Attachments)

    Bilder in Notion sind tricky. Optionen:

  • Externe Bild‑URIs beibehalten (nicht ideal für Performance und Kontrolle).
  • Bilder beim Build herunterladen und in /assets/posts// speichern; dann Pfade im Markdown anpassen.
  • Oder: Bilder in ein CDN hochladen (z. B. Cloudflare Images, S3 + CloudFront) und die URL im Frontmatter speichern.

    • Ich lade Bilder beim Notion‑Export automatisch lokal ins Repo und lasse sie von der CI zusammen mit dem restlichen Build deployen.

    Fehlerquellen und Troubleshooting

    Das sind die Probleme, die mir am häufigsten begegnet sind:

  • Rate Limits der Notion API: Bei vielen Seiten unbedingt throtteln und inkrementell aktualisieren.
  • Inkompatible Notion‑Blocks: Embeds oder komplexe Tabellen werden nicht immer korrekt in Markdown konvertiert.
  • Image‑URLs, die temporär sind: Manche Notion URLs laufen ab – daher Bilder herunterladen!
  • Infinite CI‑Loops: Wenn der Content‑Commit die Action wieder triggert, kann es Schleifen geben. Löse das mit einem separaten Bot‑Token oder conditional checks (z. B. ignore commits von github-actions bot).

    • Ein Beispiel‑Workflow in Worten

    So läuft es bei mir konkret ab:

  • Ich schreibe einen Artikel in der Notion‑Datenbank, setze Published auf true und definiere Tags und Slug.
  • Ein nächtlicher GitHub Action Job oder manuell getriggert läuft: er ruft die Notion API ab, konvertiert die neue Seite in eine Markdown‑Datei mit Frontmatter und pusht den Content‑Branch.
  • Ein weiterer Job prüft den Content‑Branch, baut mit Eleventy und deployed auf GitHub Pages.
  • Auf der Seite prüfe ich die Vorschau und merge dann den Content‑Branch in main (bei Bedarf automatisch via Action, wenn Checks grün sind).

    • Tipps für Templates und SEO

    Ein paar Dinge, die ich in meinen Templates berücksichtige:

  • Meta‑Tags aus dem Frontmatter füllen: title, description, og:image.
  • Structured Data (JSON‑LD) mit Post‑Metadaten generieren.
  • Canonical URLs setzen, falls du auch eine PWA oder alternative Pfade nutzt.
  • Preview‑Snippets: generiere ein kurzes Excerpt aus den ersten 160 Zeichen oder aus einem expliziten Excerpt‑Feld in Notion.

    • Weiterführende Werkzeuge

    Je nach Bedarf habe ich folgende Tools eingesetzt oder getestet:

    ToolUse case
    notion2mdSimple Konvertierung von Notion Blocks zu Markdown
    notion‑sdk (official)Direkter API‑Zugriff in Node‑Scripts
    EleventyStatic Site Generator (flexibel, schnell)
    GitHub ActionsCI/CD Pipeline

    Wenn du magst, kann ich dir ein Starter‑Repo vorbereiten mit einem Node‑Script für die Notion‑Konvertierung, einer Beispiel .eleventy.js Konfiguration und einem GitHub Actions Workflow. Sag mir kurz, welche Deployment‑Option du bevorzugst (GitHub Pages, Netlify, Vercel, S3/CloudFront), dann passe ich das Repo an.