12 KiB
Anleitung: Slides schreiben
Diese Anleitung beschreibt den Aufbau der Markdown-Dateien für slidewalk im Detail — von der Datei- und Ordnerstruktur über Frontmatter bis zu allen unterstützten Markdown-Features, Mermaid-Diagrammen und rohem HTML.
Ein vollständiges, lauffähiges Beispiel-Deck liegt unter
examples/demo/.
1. Datei- und Ordnerstruktur
-
Eine Datei = ein Slide — es sei denn, die Datei enthält
<!-- new slide -->-Markierungen, dann wird sie in mehrere Slides aufgeteilt, siehe Abschnitt 6a. Jede.md-Datei in dem Ordner, den du anslidewalkübergibst, wird standardmäßig zu genau einem Slide. -
Reihenfolge über Dateiname-Präfix. Die Dateien werden alphabetisch sortiert; ein numerischer Präfix mit Lücken macht das Einschieben späterer Slides einfach, ohne bestehende Dateien umbenennen zu müssen:
content/ 010-intro.md 020-features.md 025-nachtrag.md <- später eingeschoben, keine Umbenennung nötig 030-diagramm.md 040-outro.md -
Als Slides werden nur Dateien mit der Endung
.mddirekt im übergebenen Ordner berücksichtigt (nicht rekursiv) — Unterordner-Inhalte werden nie als eigene Slides eingelesen. -
Alle anderen Dateien im Ordner (Bilder, sonstige Assets), auch in Unterordnern, werden sowohl vom Dev-Server als auch beim
-build-Export automatisch mit ausgeliefert bzw. mitkopiert — siehe Abschnitt „Bilder". Ausgenommen sind Dotfiles/Dot-Ordner (.git,.DS_Store, …), die werden ignoriert.
2. Frontmatter
Jede Slide-Datei kann optional mit einem YAML-Frontmatter-Block beginnen,
eingerahmt von ----Zeilen:
---
title: Meine Überschrift
class: intro
notes: Nur für die Sprechernotizen gedacht.
skip: false
---
# Der eigentliche Slide-Inhalt
Fehlt das Frontmatter komplett, ist das kein Fehler — die Datei wird einfach komplett als Markdown-Body behandelt.
| Feld | Typ | Standard | Bedeutung |
|---|---|---|---|
title |
string | leer | Titel des Slides. Aktuell informativ, wird nicht automatisch ins Slide-HTML gerendert. |
class |
string | leer | Wird als zusätzliche CSS-Klasse auf das <section>-Element des Slides angewendet (z. B. für eigene Layout-Varianten in style.css). |
notes |
string | leer | Sprechernotizen. Werden mitgerendert (<div class="notes">), aber per CSS standardmäßig ausgeblendet (display: none). |
skip |
bool | false |
Bei true wird die Datei komplett übersprungen — taucht weder im Dev-Server noch im Export auf. Praktisch, um Entwürfe im Ordner liegen zu lassen. |
incremental |
bool | false |
Bei true werden die Top-Level-Listeneinträge (<ul>/<ol>) der Slide einzeln nacheinander eingeblendet ("Fragments"), siehe Abschnitt 6. |
Eigene class-Werte nutzen
Der Wert von class landet 1:1 als zusätzliche CSS-Klasse im HTML:
---
class: intro
---
erzeugt:
<section class="slide intro" data-slide="1">…</section>
Damit du eigene Slide-Varianten stylen kannst, ergänze web/assets/style.css
um passende Regeln, z. B.:
section.slide.intro h1 {
font-size: var(--font-size-xxl);
text-align: center;
}
3. Markdown-Grundlagen
Der Markdown-Body jeder Datei wird mit goldmark
inklusive GitHub-Flavored-Markdown-Erweiterungen gerendert. Es steht das
komplette gängige Markdown-Set zur Verfügung:
Überschriften
# H1
## H2
### H3
h1–h3 haben eigene Größenstufen in style.css (--font-size-xxl,
--font-size-xl, --font-size-lg); h4–h6 erben die Basisgröße.
Absätze, Betonung, Durchstreichen
Normaler Text mit *kursiv*, **fett** und ~~durchgestrichen~~.
Listen
- Punkt eins
- Punkt zwei
- verschachtelt
1. Erster Schritt
2. Zweiter Schritt
Task-Listen (GFM)
- [x] Erledigt
- [ ] Offen
Rendert als Checkbox-Liste (die Checkboxen sind nicht interaktiv, rein optisch).
Links und Auto-Links
[slidewalk auf GitHub](https://github.com/) — expliziter Link.
https://example.com — nackte URLs werden automatisch verlinkt (Linkify).
Bilder
Bildpfade sind relativ zur ausgelieferten HTML-Datei zu verstehen, z. B. legst
du das Bild unter img/bild.png im Slide-Ordner ab und referenzierst es mit
. Sowohl der Dev-Server als auch der
-build-Export liefern bzw. kopieren alle Dateien aus dem Slide-Ordner
automatisch mit (auch aus Unterordnern) — außer den .md-Dateien selbst und
Dotfiles/Dot-Ordnern (.git, .DS_Store, …). Ein manuelles Kopieren ist
nicht mehr nötig.
Zitate
> Ein Blockquote für Zitate oder Hervorhebungen.
Tabellen (GFM)
| Feature | Status |
| ------------ | ------ |
| Markdown | ✅ |
| Mermaid | ✅ |
| Live-Reload | ✅ |
Inline-Code und Codeblöcke
Ein `inline`-Code-Ausschnitt.
```go
func main() {
fmt.Println("hallo")
}
```
Codeblöcke mit Sprachangabe (go, js, …) werden automatisch
Syntax-highlighted, sofern Chroma
(die Highlighting-Bibliothek, die slidewalk dafür einbindet) die Sprache
kennt — das Highlighting passiert beim Parsen in Go, es ist also kein
zusätzliches JavaScript im Browser nötig. Farben kommen aus der
mitausgelieferten chroma.css und passen sich automatisch dem Dark Mode an
(Theme github hell / github-dark dunkel).
Kennt Chroma die angegebene Sprache nicht (oder es wurde gar keine
Sprache angegeben), fällt der Codeblock automatisch auf einfaches
<pre><code class="language-<sprache>"> ohne Highlighting zurück —
funktioniert also in jedem Fall, nur eben ohne Farben.
Fußnoten (GFM/PHP-Markdown-Extra-Stil)
Eine Aussage mit Beleg.[^1]
[^1]: Die Fußnote selbst, wird am Ende des Slides gesammelt dargestellt.
4. Mermaid-Diagramme
Ein Codeblock mit der Sprache mermaid wird nicht als Code dargestellt,
sondern als Diagramm gerendert:
```mermaid
graph TD
A[Start] --> B{Frage?}
B -->|Ja| C[Weiter]
B -->|Nein| D[Stop]
```
Details dazu, wie das technisch funktioniert:
- Der Codeblock wird zu
<pre class="mermaid">…</pre>statt des normalen<pre><code class="language-mermaid">…</code></pre>— das ist das Format, dasmermaid.jserwartet. - Mermaid wird lokal aus
web/assets/vendor/mermaid.min.jsgeladen, kein CDN-Zugriff nötig. - Das Theme (
mermaid.initialize({ theme: …, themeVariables: … })) wird automatisch an die CSS-Variablen deinesstyle.cssangeglichen (Hintergrund-, Text- und Akzentfarbe, Schriftart) und reagiert auf Dark-Mode (prefers-color-scheme). - Aus Performance-Gründen wird ein Diagramm erst gerendert, wenn der Slide,
auf dem es liegt, tatsächlich aktiv wird (
mermaid.run({ nodes: […] })gezielt pro Slide, nicht für das gesamte Dokument beim Laden).
Alle gängigen Mermaid-Diagrammtypen funktionieren, z. B.:
```mermaid
sequenceDiagram
Alice->>Bob: Hallo Bob
Bob-->>Alice: Hallo Alice
```
```mermaid
pie title Anteile
"A" : 40
"B" : 35
"C" : 25
```
5. Rohes HTML in Markdown
Für Fälle, die reines Markdown nicht abdeckt (z. B. Layout-<div>s,
<iframe>s, Inline-Styles), ist rohes HTML — sowohl block- als auch
inline-artig — direkt im Markdown erlaubt. Das ist Markdown-Standardverhalten
und in slidewalk explizit aktiviert (goldmark läuft mit html.WithUnsafe(),
d. h. HTML wird nicht escaped, sondern unverändert übernommen).
Block-HTML
<div class="side-by-side">
<div>
## Links
Normaler Markdown-Text funktioniert auch **innerhalb** von HTML-Blöcken,
solange eine Leerzeile davor steht.
</div>
<div>
## Rechts
Zweite Spalte.
</div>
</div>
Inline-HTML
Ein Wort mit <span style="color: var(--color-accent)">Akzentfarbe</span>
mitten im Satz, oder ein <br> für einen manuellen Zeilenumbruch.
Eingebettete Inhalte
<iframe src="https://example.com" width="100%" height="400" style="border:0"></iframe>
Hinweis: Da rohes HTML ungefiltert übernommen wird, solltest du nur Markdown-Dateien aus vertrauenswürdiger Quelle präsentieren (z. B. deinem eigenen Repository) — genau wie bei jedem anderen selbst geschriebenen HTML-Dokument.
6. Fragments (Bullet-Points einzeln einblenden)
Standardmäßig erscheint der komplette Inhalt einer Slide auf einmal. Für Stichpunktlisten, die im Vortrag einzeln nacheinander aufgedeckt werden sollen, gibt es zwei Wege:
Automatisch für die ganze Liste, per Frontmatter:
---
incremental: true
---
## Agenda
- Punkt eins
- Punkt zwei
- Punkt drei
Jeder Top-Level-Listeneintrag (<ul>/<ol> direkt in der Slide) wird dann
einzeln als "Fragment" behandelt: →/Space blendet zunächst das nächste
Fragment ein, statt sofort zum nächsten Slide zu springen; erst wenn alle
Fragmente sichtbar sind, geht es zum nächsten Slide weiter. ← funktioniert
spiegelbildlich rückwärts. Der URL-Hash spiegelt den Fortschritt (z. B.
#4.2 für Slide 4, zweites Fragment sichtbar).
Gezielt für einzelne Elemente, per raw HTML mit der Klasse fragment
(funktioniert unabhängig von incremental, auch für Absätze, Bilder,
einzelne Listeneinträge etc.):
<p class="fragment">Dieser Absatz erscheint erst auf Tastendruck.</p>
6a. Manueller Seitenumbruch in einer Datei
Eine Zeile mit <!-- new slide --> teilt die aktuelle Datei an dieser
Stelle in mehrere Slides auf — praktisch, wenn zusammengehöriger Inhalt aus
Vortrags-Sicht trotzdem auf mehrere Slides verteilt werden soll, ohne die
Datei selbst in mehrere Dateien aufzuteilen:
---
title: Ergebnisse
---
# Ergebnisse (1/2)
- Punkt eins
- Punkt zwei
<!-- new slide -->
# Ergebnisse (2/2)
- Punkt drei
Alle so entstehenden Slides teilen sich das Frontmatter der Datei
(title, class, notes, incremental gelten für jeden Teil gleich).
Der Marker muss allein auf seiner Zeile stehen (führende/nachfolgende
Leerzeichen sind egal). Innerhalb eines Codeblocks — egal ob mit
``` oder ~~~ eingezäunt — wird er als reiner Text behandelt und
löst keinen Umbruch aus; so lässt sich der Marker auch in Beispiel-Code
zeigen, ohne die Slide ungewollt zu splitten.
7. Übersichts-/Grid-Modus
Taste O schaltet einen Übersichts-Modus um, der alle Slides gleichzeitig
als Miniaturansicht zeigt (nützlich, um in einem größeren Deck schnell zu
einem bestimmten Slide zu springen). Ein Klick auf ein Slide springt direkt
dorthin und verlässt den Modus; Escape oder erneutes O verlassen ihn
ohne Slide-Wechsel. Der Modus ist reines Client-JS/CSS (.grid-mode auf
<body>), es gibt keinen zusätzlichen Server-Endpunkt dafür.
8. Vollständiges Beispiel
---
title: Roadmap
class: roadmap
notes: Vor diesem Slide kurz auf offene Fragen aus dem letzten Meeting eingehen.
---
## Roadmap Q3
- [x] Parser & Renderer
- [x] Mermaid-Support
- [ ] Presenter-Notizen-Ansicht
| Meilenstein | Status |
| --------------- | ----------- |
| MVP | ✅ erledigt |
| Live-Reload | ✅ erledigt |
| v1.0 | 🚧 in Arbeit |
> Details zur Timeline gerne im Anschluss.
```mermaid
gantt
title Grobe Timeline
dateFormat YYYY-MM-DD
section MVP
Parser & Renderer :done, 2026-06-01, 14d
Navigation & CSS :done, 2026-06-15, 10d
section v1.0
Presenter View :active, 2026-07-01, 10d
Weitere lauffähige Beispiele findest du in examples/demo/.