safe-carousel

Ein reproduzierbarer Generator für LinkedIn-PDF-Karussells auf Basis von Markdown, YAML-Frontmatter und einem CSS-Theme.

Der Generator rendert jede Folie mit Chromium in exakt 1080 × 1350 Pixel, prüft das Layout auf Überläufe und erzeugt anschließend PNG-Dateien sowie eine Vektor- und eine Raster-PDF. Weil Social-Media-Plattformen gelegentlich überraschend kreative Vorstellungen von PDF-Kompatibilität entwickeln.

Funktionen

• Inhalte als Markdown mit YAML-Frontmatter
• mehrere Decks innerhalb eines Projekts
• wiederverwendbare CSS-Themes
• feste LinkedIn-Größe von 1080 × 1350 Pixel
• proportionale Bilddarstellung mit object-fit: cover
• automatische Prüfung auf Text- und Layout-Überläufe
• PNG-Export jeder einzelnen Folie
• Vektor-PDF mit durchsuchbarem Text
• Raster-PDF als robuster Fallback
• HTML-Vorschau
• Contact Sheet zur schnellen Sichtprüfung

Voraussetzungen

Erforderlich

• Node.js 20 oder neuer
• npm
• ein von Playwright unterstützter Chromium-Browser

Die verwendete Node-Version lässt sich prüfen mit:

node --version

Chromium installieren

Am einfachsten wird Chromium über Playwright installiert:

npx playwright install chromium

Unter Linux können zusätzlich Systemabhängigkeiten erforderlich sein:

npx playwright install --with-deps chromium

Alternativ kann ein bereits installierter Chromium-Browser verwendet werden. Der Pfad wird über die Umgebungsvariable CHROMIUM_PATH gesetzt:

Linux

export CHROMIUM_PATH=/usr/bin/chromium

Windows PowerShell

$env:CHROMIUM_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"

Windows Eingabeaufforderung

set CHROMIUM_PATH=C:\Program Files\Google\Chrome\Application\chrome.exe

Hinweis: Der aktuelle Renderer verwendet Playwrights Chromium automatisch. CHROMIUM_PATH ist vor allem dann nützlich, wenn bewusst ein lokal installierter Browser verwendet werden soll.

Installation

Repository klonen oder entpacken und anschließend die Abhängigkeiten installieren:

npm install

Danach gegebenenfalls Chromium installieren:

npx playwright install chromium

Projektstruktur

safe-carousel/
├── decks/
│   └── week-01/
│       ├── deck.json
│       ├── assets/
│       │   └── beispiel.jpg
│       └── slides/
│           ├── 01.md
│           ├── 02.md
│           └── ...
├── dist/
├── src/
│   ├── cli.js
│   ├── icons.js
│   └── render.js
├── themes/
│   └── safesite/
│       └── theme.css
└── package.json

Jedes Carousel liegt als eigenes Deck unter decks/<deck-name>/.

Ein Deck konfigurieren

Die Datei deck.json legt Theme und Ausgabegröße fest:

{
  "theme": "safesite",
  "width": 1080,
  "height": 1350
}

Die Werte width und height sollten für LinkedIn bei 1080 × 1350 bleiben.

Ein Deck bauen

npm run build -- week-01

Alternativ direkt über die CLI:

node src/cli.js build week-01

Ohne Decknamen wird standardmäßig week-01 verwendet:

npm run build

Vorschau erzeugen

npm run preview -- week-01

oder:

node src/cli.js preview week-01

Die Vorschau wird unter folgendem Pfad erzeugt:

dist/week-01/preview.html

Ausgabe

Nach einem erfolgreichen Build entsteht beispielsweise:

dist/week-01/
├── png/
│   ├── 01.png
│   ├── 02.png
│   └── ...
├── contact-sheet.png
├── preview.html
├── week-01.pdf
└── week-01-raster.pdf

• week-01.pdf: bevorzugte Vektor-PDF mit durchsuchbarem Text
• week-01-raster.pdf: PDF aus den gerenderten PNG-Seiten
• png/: einzelne Folien
• contact-sheet.png: kompakte Übersicht aller Folien
• preview.html: Browser-Vorschau

Folien erstellen

Jede Folie ist eine Markdown-Datei unter:

decks/<deck-name>/slides/

Die Dateinamen bestimmen die Reihenfolge und sollten daher nummeriert werden:

01.md
02.md
03.md

Eine Folie besteht aus YAML-Frontmatter und optionalem Markdown-Inhalt:

---
layout: photo-right
title: Meine Überschrift
subtitle: Eine kurze Einordnung.
image: beispiel.jpg
items:
  - icon: check
    text: Ein Punkt
footerCard: "Eine abschließende Aussage."
---

Zusätzlicher Fließtext in Markdown.

Bilder gehören nach:

decks/<deck-name>/assets/

Unterstützte Felder

Feld	Bedeutung
layout	Layout der Folie
title	Hauptüberschrift, HTML wie <br> ist möglich
subtitle	Unterüberschrift
image	Dateiname aus dem assets-Ordner
items	Liste aus Icon und Text
quote	hervorgehobene Aussage
footerCard	Karte im unteren Inhaltsbereich
eyebrow	große dekorative Zeichen oder kurze Einleitung
symbol	großes Symbol bei question
art	aktuell unterstützte Illustration, z. B. raspberry

Layouts

hero

Großer Einstieg mit Text links und Bild rechts.

---
layout: hero
title: Vom Problem<br>zum Produkt
subtitle: Eine kurze Einführung.
image: titelbild.jpg
footerCard: "Der Einstieg in die Geschichte."
---

photo-right

Text und Listen links, hochformatiges Bild rechts.

---
layout: photo-right
title: Die ersten Daten
subtitle: Der Collector liefert echte Messwerte.
image: collector.jpg
items:
  - icon: antenna
    text: Sensoren anbinden
  - icon: database
    text: Daten speichern
---

photo-bottom

Text über einem vollbreiten Bild. Dieses Layout eignet sich besonders für Dashboards, Architekturdiagramme und breite Screenshots.

---
layout: photo-bottom
title: Das erste Dashboard
subtitle: Zum ersten Mal wurde das System sichtbar.
image: dashboard.png
items:
  - icon: chart
    text: Live-Daten anzeigen
  - icon: database
    text: Historie vorbereiten
footerCard: "Vom funktionierenden Stack zum Produkt."
---

Das Bild belegt den unteren Bereich der Folie und wird proportional zugeschnitten. Für gute Ergebnisse sollten breite Bilder oder Screenshots verwendet werden.

plain

Breites Textlayout ohne Bild.

---
layout: plain
title: Meine Learnings
items:
  - icon: check
    text: KI programmiert schnell.
  - icon: brain
    text: Menschen liefern Kontext und Entscheidungen.
---

question

Layout für Leitfragen, Zitate oder Übergänge.

---
layout: question
title: Die entscheidende Frage
quote: Kann KI heute ernsthaft<br>Software entwickeln?
symbol: KI
---

Verfügbare Icons

Die Icons werden als Inline-SVGs in src/icons.js gepflegt. Sie sind weder externe Bilddateien noch eine Icon-Schriftart.

Aktuell stehen unter anderem folgende Namen zur Verfügung:

check
bluetooth
usb
wifi
code
server
antenna
chart
database
brain
warning

Ein unbekannter Icon-Name fällt derzeit auf check zurück. Ein Tippfehler sieht deshalb nicht kaputt aus, sondern nur überzeugend falsch. Neue Icons werden direkt im icons-Objekt in src/icons.js ergänzt.

Bilder

• JPG, PNG und WebP werden unterstützt.
• Bilder werden proportional dargestellt und mit object-fit: cover zugeschnitten.
• Das Seitenverhältnis sollte zum gewählten Layout passen.
• photo-right bevorzugt eher hochformatige Motive.
• photo-bottom bevorzugt breite Screenshots oder Diagramme.

Validierung

Vor dem Export prüft der Generator:

• Anzahl der gerenderten Folien
• Überläufe über die Foliengrenzen
• Überläufe innerhalb des Inhaltsbereichs
• konsistente Bildflächen innerhalb desselben Layouts
• ausreichenden Abstand zwischen Text und rechter Bildfläche
• exakte PNG-Größe gemäß deck.json

Bei einem Fehler wird der Build abgebrochen und eine Beschreibung ausgegeben.

Typische Fehler

Chromium wurde nicht gefunden

Executable doesn't exist

Lösung:

npx playwright install chromium

oder CHROMIUM_PATH auf einen installierten Browser setzen.

Das falsche Icon wird angezeigt

Prüfen, ob der Icon-Name exakt in src/icons.js existiert. Unbekannte Namen werden als check dargestellt.

Layout overflow

Text kürzen, weniger Listeneinträge verwenden oder ein Layout mit mehr Inhaltsfläche wählen. Für breite Screenshots ist photo-bottom meist geeigneter als photo-right.

Bild wurde nicht gefunden

Der Dateiname in image: muss exakt mit einer Datei unter decks/<deck-name>/assets/ übereinstimmen. Auf Linux ist auch die Groß- und Kleinschreibung relevant.

Lizenz und Nutzung

Das Projekt ist experimentell. Nutzung auf eigene Gefahr. Weitere Informationen stehen in LICENSE.md.