slidewalk/README.md

slidewalk

Ein minimalistisches, selbstgebautes Tool zum Präsentieren von Markdown-Slides im Browser, mit Mermaid-Support. Geschrieben in Go, das Ergebnis ist ein einziges Binary.

• Nur Markdown als Quelle (rohes HTML ist bei Bedarf inline erlaubt)
• Eine Datei = ein Slide, Reihenfolge über Dateiname-Präfix (010-intro.md, 020-...)
• Vendored Mermaid, kein CDN nötig
• Syntax-Highlighting für Codeblöcke (serverseitig via Chroma, kein Client-JS)
• Tastatur- und Maus-Navigation, URL-Hash spiegelt den aktuellen Slide
• Dev-Server mit Live-Reload oder statischer Export als ein HTML-Dokument
• Dark Mode von Anfang an

Installation

Voraussetzung ist ein installiertes Go (siehe go.mod für die Mindestversion).

go build -o slidewalk ./cmd/slidewalk

Das erzeugt ein einziges Binary slidewalk ohne weitere Laufzeit-Abhängigkeiten (alle Assets sind über embed.FS eingebettet).

Nutzung

Ein Beispiel-Deck liegt unter examples/demo/.

Dev-Server (Standard)

slidewalk ./examples/demo

Startet einen lokalen Server (Standard-Adresse 127.0.0.1:8080) und liefert die Präsentation aus. Änderungen an den Markdown-Dateien lösen automatisch ein Neuladen im Browser aus (Live-Reload über Server-Sent Events).

Flags müssen vor dem Ordner-Pfad stehen:

slidewalk [-addr <host:port>] <ordner>

Während der Entwicklung von slidewalk selbst (ohne vorheriges go build) geht das auch direkt mit go run:

go run ./cmd/slidewalk ./examples/demo

Statischer Export

slidewalk -build ./dist ./examples/demo

Schreibt die gerenderte Präsentation als eigenständiges HTML-Dokument nach ./dist. Alle benötigten Assets (style.css, chroma.css, nav.js, mermaid.min.js) landen dabei in ./dist/vendor/ — außer der exportierten HTML-Datei selbst liegt also nichts von slidewalk lose im Zielordner. Eigene Dateien (Bilder etc.) werden unverändert an ihrem relativen Pfad mitkopiert. Das Ergebnis lässt sich ohne Server direkt im Browser öffnen oder auf beliebigem Static Hosting ausliefern.

slidewalk [-build <zielordner>] [-out <datei.html>] <ordner>

Flag	Default	Bedeutung
-build	–	Zielordner für den statischen Export; ohne diesen Flag startet der Dev-Server
-out	index.html	Name der exportierten HTML-Datei (nur mit -build)
-addr	127.0.0.1:8080	Adresse, auf der der Dev-Server lauscht

Navigation

Eingabe	Aktion
→, Space, PageDown	nächstes Fragment, dann nächster Slide
←, PageUp	vorheriges Fragment, dann vorheriger Slide
Home	erster Slide
End	letzter Slide
O	Übersichts-/Grid-Modus an/aus
Escape (im Grid-Modus)	Grid-Modus verlassen, ohne Slide zu wechseln
Klick links/rechts, Pfeil-Buttons	Slide wechseln
Klick auf Slide (im Grid-Modus)	zu diesem Slide springen, Grid-Modus verlassen

Der aktuelle Slide (und ggf. Fragment-Fortschritt) wird im URL-Hash gespiegelt (z. B. #3 oder #3.2 für Slide 3, zweites Fragment sichtbar) und beim Laden daraus wiederhergestellt.

PDF-Export

Über den Druckdialog des Browsers (Cmd/Ctrl+P → „Als PDF sichern“) lässt sich die Präsentation direkt als PDF exportieren — jede Slide wird dabei auf eine eigene Seite gedruckt, Navigationselemente werden ausgeblendet. Das funktioniert sowohl im Dev-Server als auch mit dem statischen -build-Export.

In Chrome funktioniert das fehlerfrei inklusive automatischem Querformat. Safari ignoriert die CSS-Vorgabe für die Seitenausrichtung (bekannte WebKit-Einschränkung) und erzeugt dadurch teils Leerseiten — hier im Druckdialog manuell „Querformat“ wählen, oder für den PDF-Export auf Chrome ausweichen.

Fragments (Bullet-Points einzeln einblenden)

Setzt eine Slide-Datei incremental: true im Frontmatter, werden ihre Top-Level-Listeneinträge (<ul>/<ol>) einzeln nacheinander eingeblendet, statt alle auf einmal zu erscheinen — praktisch beim Durchgehen von Stichpunkten im Vortrag. Zusätzlich (oder alternativ) lässt sich jedes beliebige Element per raw HTML mit class="fragment" einzeln als Fragment markieren.

Manueller Seitenumbruch

Eine Zeile mit <!-- new slide --> teilt eine einzelne Slide-Datei an dieser Stelle in mehrere Slides auf — praktisch, wenn zusammengehöriger Inhalt trotzdem auf mehrere Slides verteilt werden soll, ohne die Datei selbst zu splitten. Alle so entstehenden Slides teilen sich das Frontmatter der Datei (title, class, notes, incremental).

# Erster Teil

<!-- new slide -->

# Zweiter Teil

Der Marker muss allein auf seiner Zeile stehen. Innerhalb eines Codeblocks (``` oder ~~~) wird er ignoriert und nicht als Umbruch gewertet.

Frontmatter-Referenz

Jede Slide-Datei kann optional ein YAML-Frontmatter am Dateianfang haben:

---
title: Meine Überschrift
class: intro
notes: Nur für die Sprechernotizen gedacht.
skip: false
---

# Der eigentliche Slide-Inhalt

Feld	Typ	Bedeutung
title	string	Titel des Slides; wird beim Anzeigen des Slides als Browser-Tab-Titel gesetzt (Slide-Titel · Deck-Titel)
class	string	Wird als zusätzliche CSS-Klasse auf das <section>-Element angewendet
notes	string	Sprechernotizen; werden gerendert, aber per CSS standardmäßig versteckt
skip	bool	Wenn true, wird die Datei beim Rendern/Export komplett übersprungen
incremental	bool	Wenn true, werden Top-Level-Listeneinträge der Slide einzeln nacheinander eingeblendet (Fragments)

Mermaid-Diagramme werden über normale Codeblöcke mit der Sprache mermaid eingebunden:

```mermaid
graph TD
  A --> B
```

Eine ausführliche Anleitung mit Beispielen für alle unterstützten Markdown-Features (Tabellen, Task-Listen, Fußnoten, Mermaid-Diagrammtypen, rohes HTML als Fallback etc.) findest du unter docs/markdown-guide.md.

Code-Dokumentation

Eine Übersicht über die Architektur, welche Datei wofür zuständig ist und wie die Packages zusammenspielen, findest du unter docs/architektur.md.

Cross-Compiling

Go kompiliert ohne zusätzliche Werkzeuge für andere Betriebssysteme/ Architekturen, gesteuert über die Umgebungsvariablen GOOS/GOARCH. Da alle Assets über embed.FS eingebettet sind, entsteht in jedem Fall ein einziges, eigenständiges Binary.

# macOS (Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o dist/slidewalk-darwin-arm64 ./cmd/slidewalk

# macOS (Intel)
GOOS=darwin GOARCH=amd64 go build -o dist/slidewalk-darwin-amd64 ./cmd/slidewalk

# Linux (x86_64)
GOOS=linux GOARCH=amd64 go build -o dist/slidewalk-linux-amd64 ./cmd/slidewalk

# Linux (ARM64, z. B. Raspberry Pi 4/5, AWS Graviton)
GOOS=linux GOARCH=arm64 go build -o dist/slidewalk-linux-arm64 ./cmd/slidewalk

# Windows (x86_64)
GOOS=windows GOARCH=amd64 go build -o dist/slidewalk-windows-amd64.exe ./cmd/slidewalk

Alle Zielsysteme lassen sich von einer einzigen Maschine aus bauen (kein Cross-Compiler nötig, da reines Go ohne CGO). go tool dist list zeigt alle unterstützten GOOS/GOARCH-Kombinationen.

Entwicklung

go vet ./...
go test ./...