212 lines
7.7 KiB
Markdown
212 lines
7.7 KiB
Markdown
# 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).
|
||
|
||
```sh
|
||
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)
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
slidewalk [-addr <host:port>] <ordner>
|
||
```
|
||
|
||
Während der Entwicklung von slidewalk selbst (ohne vorheriges `go build`)
|
||
geht das auch direkt mit `go run`:
|
||
|
||
```sh
|
||
go run ./cmd/slidewalk ./examples/demo
|
||
```
|
||
|
||
### Statischer Export
|
||
|
||
```sh
|
||
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.
|
||
|
||
```sh
|
||
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`).
|
||
|
||
```markdown
|
||
# 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:
|
||
|
||
```markdown
|
||
---
|
||
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:
|
||
|
||
````markdown
|
||
```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`](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`](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.
|
||
|
||
```sh
|
||
# 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
|
||
|
||
```sh
|
||
go vet ./...
|
||
go test ./...
|
||
```
|