- Shell 31.7%
- JavaScript 24.2%
- HTML 21.6%
- CSS 13%
- Jinja 5.3%
- Other 4.2%
| docs | ||
| legacy | ||
| pemmikan-arc | ||
| sample_project | ||
| scripts | ||
| templates/zentonic26 | ||
| webwizard | ||
| .gitignore | ||
| .toolctl-install | ||
| build.sh | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| cliff.toml | ||
| deploy.sh | ||
| editor.sh | ||
| LICENSE | ||
| pemmikan.md | ||
| README.md | ||
| shell.nix | ||
| tag.sh | ||
| zpub | ||
zentonic-publisher
Statischer Podcast-Website-Generator — weil dein RSS-Feed kein WordPress verdient 🎙️
Reines Bash, kein Framework; der Build braucht weder Python noch Node.
Live-Demo: demo.podcast.zentonic.org — der
fiktive „NullPointer Podcast“ aus sample_project/, unverändert gebaut.
Inhalt: Quickstart · Features · Bilder · Dokumentation · Befehle · Installation · Herkunft, Changelog, Lizenz
Quickstart
zpub init ~/podcasts/mein-podcast # 1. Tenant anlegen — sofort baubar
cd ~/podcasts/mein-podcast
zpub episode new --title "Pilotfolge" --speaker host . # 2. Folge anlegen → episodes/002/
zpub build --local . # 3. bauen → public/ (Vorschau ohne Domain)
zpub check --no-browser public # 4. prüfen: Feed, Links, Cover
cp deploy.local.toml.example deploy.local.toml # Ziel host:/pfad eintragen
zpub deploy --dry-run . # 5. Deploy-Probe, überträgt nichts
| Schritt | Was passiert | Mehr |
|---|---|---|
1 init |
podcast.toml, Beispielfolge 001, Sprecher host, theme/, Platzhalter-Cover |
Was zpub init anlegt |
2 episode new |
episodes/<slug>/episode.md mit nächster freier Nummer; danach Shownotes schreiben, MP3 nach episodes/<slug>/audio/<slug>.mp3 |
Episoden-Format |
3 build |
HTML, feed.xml, Suche, Sitemap; --local = Vorschau ohne eigene Domain ([web] url wird nur gewarnt, nicht geprüft) |
Konfiguration |
4 check |
Feed wohlgeformt, Links, Cover; ohne --no-browser zusätzlich Player-Test in Chromium + Firefox |
Prüfen |
5 deploy |
Prüfung → rsync → Live-Prüfung; ohne Ziel bricht er mit Hinweis ab, ohne --dry-run wird übertragen |
Deploy |
Vor dem echten Deploy: [web] url (https) in podcast.toml setzen, zpub build .
ohne --local laufen lassen und das Ziel in deploy.local.toml eintragen.
Ohne installiertes zpub geht jeder Befehl auch als ./zpub … im Repo
(Installation). Lieber im Browser: zpub editor .
startet den Web-Editor. Fertige Folge aus zentonic-mix
statt Schritt 2: zpub import episode mix-07.zip .
(Einzelne Folge).
Features
| Bereich | Was drin ist |
|---|---|
| Ausgabe | Statische HTML-Seiten, RSS-Feed für iTunes/Podcastindex (absolute URLs, stabile GUIDs), sitemap.xml, robots.txt, OG/Twitter-Meta, JSON-LD |
| Podcastindex | podcast:guid, podcast:locked, podcast:chapters, podcast:transcript, podcast:person, podcast:funding |
| Player | Sticky-Player überlebt Seitenwechsel (SPA-Enhancement über echten .html-Seiten), Kapitelsprung, Shownotes-Panel mit der ganzen laufenden Folge (Kopf, Shownotes, Kapitel, Kommentare, Teilen), Mitschrift aus transcript.vtt (Whisper) mit Textlinse als Laufband, Mitlaufen, Suche in der Folge und Sprung per Klick, Live-Stream und Live-Chat ([stream]), Download als No-JS-Fallback |
| Bedienung | Tastenkürzel wie bei YouTube, Knöpfe 10 s zurück und 30 s vor, Tempo 0,5× bis 3×, Teilen-Dialog mit Zeitmarke, Deep-Link ?t= (Player) |
| Suche | Volltextsuche über Titel, Shownotes, Tags, Sprecher, Kapitel — Index search.json vom Build, Suche im Browser ohne Bibliothek und ohne Fremdhost, Deep-Link suche.html?q= (Suche) |
| Alle Folgen | Tabelle aller Folgen mit kleinem Cover und Metadaten, Link im Footer jeder Seite ([web] all_episodes) |
| Übersicht | Gruppen je Staffel ([web] group_by), Seiten nach Anzahl, Jahr, Staffel oder Event ([web] page_by) — der Player läuft beim Blättern weiter (Seiten) |
| Folgenseite | Navigation zur älteren und neueren Folge mit vollem Titel, oben und am Ende der Shownotes — bloglike durchs Archiv, der Player läuft weiter; Standard, abschaltbar mit [web] episode_nav = false (Folgen-Navigation) |
| Mitwirkende | Namen führen auf eine Infoseite je Person mit Avatar, Rolle, Aliasen, Bio, Links und allen ihren Folgen; die Suche findet auch Aliase; Schalter [web] speaker_pages |
| Episoden | Eine episode.md pro Folge: TOML-Frontmatter + Markdown, ##### hh:mm:ss-Kapitel (Format); jede Folge zusätzlich als Markdown (episodes/<slug>.md, Knopf „als markdown“) |
| Anlegen, Bearbeiten | zpub episode new (nächste freie Nummer je Staffel), Web-Editor im Browser (auch bestehende Folgen, GUID und Handarbeit in der Datei bleiben; neue Mitwirkende direkt im Formular), Import aus einem Altfeed — alle über dieselbe Offline-API zpub api mit JSON ein/aus (Offline-API) |
| Veröffentlichen | Folgen mit date in der Zukunft hält der Build zurück; --as-of testet einen Stichtag, --preview baut alles nach public-preview/ (Zukunfts-Folgen) |
| Feed-Rhythmus | podcast:updateFrequency und itunes:complete aus [feed] update_*/complete (Erscheinungsrhythmus) |
| Audio | ID3-Tags, Cover, Kapitel per ffmpeg; WAV → MP3; Audio lokal, per CDN (audio_base_url) oder als externe URL ([audio] url) |
| Design | Terminal/Cyberpunk-Template zentonic26, Branding aus podcast.toml; eigenes Design als Theme-Schicht im Tenant (theme/tokens.css, Hell/Dunkel per [theme]) — Publisher-Updates kommen ohne Bruch an (Theming) |
| Werkzeuge | zpub-CLI, Site-Check inkl. Browser-Test, Deploy per rsync, lokaler Web-Editor, Mastodon-Kommentare |
| Abhängigkeiten | Kein npm, kein pip, kein Python, keine Build-Pipeline (node nur für den optionalen Browser-Check) |
Bilder
Alle Bilder zeigen die Demo aus sample_project/ und entstehen per
bash scripts/docs-screenshots.sh (headless Chromium, 1280 px breit).
| Website | |
|---|---|
![]() |
![]() |
| Folgenseite mit Kapiteln | Shownotes-Panel der laufenden Folge |
![]() |
![]() |
Suche suche.html?q=bash |
Übersicht auf Seiten (page_by) |
Web-Editor (zpub editor <tenant>) |
|
|---|---|
![]() |
![]() |
| Start | Folge anlegen, mit Staffel |
![]() |
![]() |
| Rückmeldung | Bestand danach |
![]() |
![]() |
| Fehler am Feld | Folge bearbeiten |
Dokumentation
| Thema | Wo |
|---|---|
podcast.toml — alle Abschnitte, Gruppen und Seiten der Übersicht (group_by, page_by), Erscheinungsrhythmus, Schriften, Projektstruktur |
docs/configuration.md |
episode.md — Frontmatter, Kapitel, Speaker, Offline-API (zpub episode new, zpub api) |
docs/episode-format.md |
| Check, Folgen mit Datum in der Zukunft, Deploy, Webserver | docs/deploy.md |
Altbestand aus einem Feed übernehmen (zpub import feed), fertige Folge übernehmen (zpub import episode) |
docs/import.md |
| Player: Tastenkürzel, Kapitel mit Bild und Link, Teilen, Deep-Link, Shownotes-Panel, Mitschrift, Textlinse | docs/player.md |
| Web-Editor inkl. Sicherheitsannahmen | docs/web-editor.md |
| Mastodon-Kommentare und Toot-Werkzeuge | docs/mastodon.md |
Theme-Schicht: theme/, Tokens, Blöcke, Hell/Dunkel ([theme]) |
docs/theming.md |
Datenschutzerklärung datenschutz.html aus Bausteinen ([privacy]) |
docs/privacy.md |
Downloads je Folge aus Server-Logs zählen (zpub stats, [privacy] stats) |
docs/stats.md |
Volltextsuche search.json + suche.html ([web] search) |
docs/search.md |
| Template-Interna, Theme-Vertrag (Tokens, Blöcke) | templates/zentonic26/TEMPLATE.md |
Befehle
zpub |
dahinter | Zweck |
|---|---|---|
zpub init <ordner> |
— | Tenant-Gerüst + theme/-Vorlage (keine Template-Kopie); überschreibt nie einen nicht leeren Ordner |
zpub build [--local] [--as-of <ISO>] [--preview] <tenant> [<out>] |
build.sh |
Site bauen, Default-Ausgabe <tenant>/public; Folgen mit date in der Zukunft hält der Build zurück (Folgen mit Datum in der Zukunft) |
zpub check [--no-browser] <public|url> |
scripts/check.sh |
gebaute Site prüfen |
zpub deploy [--dry-run] <tenant> |
deploy.sh |
prüfen, rsync, Live-Prüfung |
zpub import feed [--renumber] [--dry-run] <rohordner|feed.xml> <tenant> |
scripts/import-feed.sh |
Altbestand aus Feed + Rohsicherung übernehmen (Import) |
zpub import episode [--dry-run] <zip|ordner> <tenant> |
scripts/import-episode.sh |
fertigen Episodenordner (z. B. aus zentonic-mix) nach episodes/<slug>/ übernehmen, prüft vorher alles, überschreibt nie (Einzelne Folge) |
zpub episode new [optionen] [<tenant>] |
scripts/lib/episode.sh |
neue Folge episodes/<slug>/ anlegen (Default-Tenant: .); überschreibt nie — Optionen |
zpub editor [<tenant>] |
webwizard/serve.sh |
Web-Editor im Browser starten (Default-Tenant: ., Port per PORT=…); auch bash editor.sh <tenant> — Web-Editor |
zpub api <verb> [<tenant>] |
scripts/lib/episode.sh |
Offline-API für Scripts: JSON auf stdin → JSON auf stdout, Verben schema, speakers, speaker-write, episodes, next, validate, write, read, update (--slug S hält die Folge fest); Exit 0 ok · 1 ungültig · 2 Fehler · 3 existiert · 4 kein Tenant · 5 Folge nicht gefunden · 6 Datei inzwischen geändert |
zpub stats [--tenant <dir>] [--since <ISO>] [--until <ISO>] [--format table|json|csv] [--by day|month] [--append <csv>] [--bots <datei>] <logdatei…> |
scripts/stats.sh |
Audio-Downloads je Folge aus Caddy-JSON-Access-Logs (auch .gz) zählen, vereinfacht nach IAB; --append legt Tageswerte dauerhaft ab (Statistik) |
zpub version |
— | Publisher-Version |
zpub help |
— | Aufruf-Übersicht aller Befehle |
Optionen von zpub episode new
| Option | Default ohne Option |
|---|---|
--season S |
keine Staffel; Nummer zählt dann unter den Folgen ohne Staffel |
--episode N |
nächste freie Nummer der Staffel, Breite wie im Tenant (5 → 05) |
--slug S |
<staffel>-<nr> bzw. <nr> |
--title T / --subtitle T |
„Folge “ / leer |
--date ISO |
jetzt (UTC) |
--type full|trailer|bonus |
full |
--speaker ID (mehrfach oder a,b) |
Sprecher der neuesten Folge der Staffel, sonst des Tenants; explicit ebenso |
--dry-run / -n |
schreibt nichts, zeigt die episode.md |
Regeln und Felder: Offline-API.
Direktaufrufe der Scripts
# Website bauen (HTML + RSS + sitemap + Audio-Tagging pro Episode)
# Bricht ab, wenn [web] url leer ist oder nicht mit https:// beginnt (#64)
bash build.sh <projektordner> <ausgabeordner>
# Lokale file://-Vorschau ohne Domain: web.url-Prüfung nur als Warnung
bash build.sh --local <projektordner> <ausgabeordner>
# Folgen mit date nach dem Stichtag (Default: jetzt, UTC) hält der Build zurück (#127):
# --as-of setzt den Stichtag (Testen), --preview baut alles (nie nach public/)
bash build.sh --as-of 2026-12-05T06:00:00+01:00 <projektordner> <ausgabeordner>
bash build.sh --preview <projektordner> <projektordner>/public-preview
# Gebaute Site prüfen (#67): Feed, relative Links, SPA/Player in Chromium + Firefox
# Exit 1 bei mindestens einem ✗ (⚠ zählt nicht), 2 bei Aufruffehler;
# --no-browser überspringt den Browser-Teil, --keep-tmp behält Profile/Logs
# Am Sample läuft zusätzlich die Escape-Matrix (#132, rund 8 s, Pflicht vor Release)
bash scripts/check.sh [--no-browser] [--keep-tmp] sample_project/public
bash scripts/check.sh https://demo.podcast.zentonic.org/
# Escape-Matrix einzeln (#79): Sample mit Nutzlast bauen und zurücklesen
bash scripts/check/escape-test.sh [--check] <arbeitsverzeichnis>
# Deploy (Ziel: ZT_DEPLOY_TARGET > deploy.local.toml > podcast.toml)
bash deploy.sh [-n|--dry-run] [projektordner]
# Nur Audio taggen (ID3 + Cover + Kapitel, standalone)
bash scripts/tag.sh <ep-json> <site-json> <ep-dir> <out-dir>
# Web-Editor — Episode anlegen und bearbeiten, Audio/Cover hochladen, Build triggern
zpub editor <projektordner> # → http://127.0.0.1:8042 (auch: bash editor.sh)
# Mastodon: Toot-Vorlage, Token, Posten
bash scripts/mastodon-toot.sh <tenant> <slug>
bash scripts/mastodon-token.sh [--manual|--check] <tenant>
bash scripts/mastodon-post.sh [--dry-run] <tenant> <slug>
# Downloads zählen (#134) und Fixture-Test mit exakten Zahlen
bash scripts/stats.sh --tenant <projektordner> [--format json] <access.log…>
bash scripts/check/stats-test.sh
# Feed-Import (#135): Plan-Prüfung vor dem Schreiben, synthetische Feeds
bash scripts/check/import-test.sh [<arbeitsverzeichnis>]
# Folgen-Import (#170): Ordner/Zip, Prüfungen, nie überschreiben
bash scripts/check/import-episode-test.sh [<arbeitsverzeichnis>]
# Selbsttest Folge bearbeiten (zpub api read/update, läuft auch in check.sh am Sample)
bash scripts/check/episode-edit-test.sh [<arbeitsverzeichnis>]
# Selbsttest Mitwirkende anlegen (zpub api speaker-write, Editor, Browser; auch in check.sh am Sample)
bash scripts/check/speaker-test.sh [<arbeitsverzeichnis>]
# Doku-Pflege je Release (#131): Abgleich Doku ↔ Code, Screenshots neu
bash scripts/check/docs-drift.sh [--summary] # Exit 1 bei Befunden
bash scripts/docs-screenshots.sh [--work <ordner>] [<ausgabe>] # → docs/screenshots/
Was zpub init anlegt
Ein Podcast ist ein eigener Ordner (eigenes Repo) außerhalb des Publishers —
der Tenant (#102). zpub init überschreibt nie einen nicht leeren Ordner.
| Angelegt | Inhalt |
|---|---|
podcast.toml |
Konfiguration mit [publisher] version |
episodes/001/episode.md |
Beispielfolge ohne Audio |
speaker/host/speaker.toml |
Beispiel-Speaker |
cover.png, site.webmanifest |
Platzhalter (Cover nur mit ImageMagick); Favicons erzeugt der Build aus dem Cover (#125) |
theme/tokens.css, theme/README.md |
Design-Tokens (alle zentonic26-Werte auskommentiert) — hier wird das Design angepasst |
.gitignore |
sperrt public/, public-preview/, deploy.local.toml, *.secret.toml; Audio wird im Tenant versioniert |
deploy.local.toml.example, README.md |
Deploy-Vorlage, Kurzanleitung |
- Template: kommt aus dem Publisher, das Design liegt in
<tenant>/theme/(Theming). Notausgang: eine Kopie unter<tenant>/templates/<name>/hat weiter Vorrang — der Build warnt dann, weil Publisher-Updates dort nicht ankommen. - Versionsbindung: Weicht der installierte Publisher von
[publisher] versionab, warnt der Build (kein Abbruch); ohne den Schlüssel bleibt er still. - Ohne Audio: Die Folge baut, hat aber keine Enclosure —
checkmeldet⚠ enclosure length(Exit 0), bis die erste MP3 unterepisodes/<nr>/audio/liegt.
Migration von Altdaten (episode.json + shownotes.md)
bash legacy/legacy_to_md.sh <source-episodes-dir> <target-episodes-dir>
bash legacy/legacy_speakers.sh <source-root> <target-root>
legacy_speakers.sh erwartet speaker/<id>/avatar.* und
episodes/<name>/episode.json unter <source-root> und legt
speaker/<id>/{avatar.*, speaker.toml} unter <target-root> an.
Installation
git clone ssh://git@forgejo.mueller.network:2222/Zentonic/zentonic-publisher.git
cd zentonic-publisher
bash build.sh sample_project/ /tmp/preview # Probe-Build der Demo
| Weg | Was |
|---|---|
| toolctl | verteilt den Publisher; der Hook .toolctl-install legt nur ~/bin/zpub als Symlink auf die Worktree an (idempotent, fremde Dateien/Symlinks werden gemeldet, nie überschrieben). Die Registrierung im toolctl-Repo folgt, sobald zpub auf main released ist. |
| Nix | nix-shell liefert alle Werkzeuge für Build, Check und Deploy (inkl. chromium/firefox/node). Der shellHook setzt unset LD_LIBRARY_PATH — ein fremder Bibliothekspfad lässt sonst chromium und ffprobe mit GLIBC_… not found scheitern (#57). |
| von Hand | Werkzeuge aus der Tabelle unten installieren |
nix-shell # interaktiv
nix-shell --run 'bash build.sh sample_project sample_project/public'
Die Demo-MP3s liegen nur in sample_project/public/audio/ (getrackt). Ein
Build in einen anderen Ordner läuft durch, die Folgen haben dort aber keine
Enclosure und keinen Play-Button; mit Audio: bash build.sh sample_project sample_project/public.
Abhängigkeiten
| Werkzeug | Gebraucht für |
|---|---|
bash jq yq pandoc minijinja-cli xxd sha1sum |
Build |
ffmpeg (mit libmp3lame) |
Audio-Tagging, WAV → MP3 |
imagemagick (magick) |
optional: Cover-Prüfung, cover-600.jpg, Platzhalter-Cover bei zpub init |
socat |
nur Web-Editor |
flock (util-linux) |
nur Bearbeiten: Sperre in zpub api update, ohne sie bleibt die Hash-Prüfung |
unzip (zipinfo) |
nur zpub import episode mit Zip (#170); zip nur für dessen Test |
curl |
scripts/check.sh (live), deploy.sh, scripts/mastodon-token.sh / mastodon-post.sh |
node chromium firefox |
nur Browser-Teil von scripts/check.sh (node auch als lokaler Testserver) |
rsync ssh |
nur deploy.sh |
yq = mikefarah/yq v4 (Go-Binary, liest TOML: yq -p toml -o json, #82) —
nicht das gleichnamige python-yq. Build, Deploy, Web-Editor und die
Mastodon-Scripts lesen TOML nur über scripts/toml.sh (#94), prüfen die
Variante und brechen sonst mit Hinweis ab.
Herkunft, Changelog, Lizenz
Inspiriert durch Mikrowelle OS von Thomas Skowron — vollständige Neuentwicklung in Bash. Änderungen: CHANGELOG.md.
MIT — holm / Christian Müller, unter Zuhilfenahme von Claude (Anthropic).










