419 lines
12 KiB
Markdown
419 lines
12 KiB
Markdown
# 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/`](../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](#6a-manueller-seitenumbruch-in-einer-datei).
|
||
Jede `.md`-Datei in dem Ordner, den du an `slidewalk` ü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 `.md` **direkt** 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"](#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:
|
||
|
||
```markdown
|
||
---
|
||
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](#6-fragments-bullet-points-einzeln-einblenden). |
|
||
|
||
### Eigene `class`-Werte nutzen
|
||
|
||
Der Wert von `class` landet 1:1 als zusätzliche CSS-Klasse im HTML:
|
||
|
||
```markdown
|
||
---
|
||
class: intro
|
||
---
|
||
```
|
||
|
||
erzeugt:
|
||
|
||
```html
|
||
<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.:
|
||
|
||
```css
|
||
section.slide.intro h1 {
|
||
font-size: var(--font-size-xxl);
|
||
text-align: center;
|
||
}
|
||
```
|
||
|
||
## 3. Markdown-Grundlagen
|
||
|
||
Der Markdown-Body jeder Datei wird mit [`goldmark`](https://github.com/yuin/goldmark)
|
||
inklusive GitHub-Flavored-Markdown-Erweiterungen gerendert. Es steht das
|
||
komplette gängige Markdown-Set zur Verfügung:
|
||
|
||
### Überschriften
|
||
|
||
```markdown
|
||
# 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
|
||
|
||
```markdown
|
||
Normaler Text mit *kursiv*, **fett** und ~~durchgestrichen~~.
|
||
```
|
||
|
||
### Listen
|
||
|
||
```markdown
|
||
- Punkt eins
|
||
- Punkt zwei
|
||
- verschachtelt
|
||
|
||
1. Erster Schritt
|
||
2. Zweiter Schritt
|
||
```
|
||
|
||
### Task-Listen (GFM)
|
||
|
||
```markdown
|
||
- [x] Erledigt
|
||
- [ ] Offen
|
||
```
|
||
|
||
Rendert als Checkbox-Liste (die Checkboxen sind nicht interaktiv, rein
|
||
optisch).
|
||
|
||
### Links und Auto-Links
|
||
|
||
```markdown
|
||
[slidewalk auf GitHub](https://github.com/) — expliziter Link.
|
||
|
||
https://example.com — nackte URLs werden automatisch verlinkt (Linkify).
|
||
```
|
||
|
||
### Bilder
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
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
|
||
|
||
```markdown
|
||
> Ein Blockquote für Zitate oder Hervorhebungen.
|
||
```
|
||
|
||
### Tabellen (GFM)
|
||
|
||
```markdown
|
||
| Feature | Status |
|
||
| ------------ | ------ |
|
||
| Markdown | ✅ |
|
||
| Mermaid | ✅ |
|
||
| Live-Reload | ✅ |
|
||
```
|
||
|
||
### Inline-Code und Codeblöcke
|
||
|
||
````markdown
|
||
Ein `inline`-Code-Ausschnitt.
|
||
|
||
```go
|
||
func main() {
|
||
fmt.Println("hallo")
|
||
}
|
||
```
|
||
````
|
||
|
||
Codeblöcke mit Sprachangabe (```go, ```js, …) werden automatisch
|
||
Syntax-highlighted, sofern [Chroma](https://github.com/alecthomas/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)
|
||
|
||
```markdown
|
||
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:
|
||
|
||
````markdown
|
||
```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,
|
||
das `mermaid.js` erwartet.
|
||
- Mermaid wird lokal aus `web/assets/vendor/mermaid.min.js` geladen, kein
|
||
CDN-Zugriff nötig.
|
||
- Das Theme (`mermaid.initialize({ theme: …, themeVariables: … })`) wird
|
||
automatisch an die CSS-Variablen deines `style.css` angeglichen
|
||
(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.:
|
||
|
||
````markdown
|
||
```mermaid
|
||
sequenceDiagram
|
||
Alice->>Bob: Hallo Bob
|
||
Bob-->>Alice: Hallo Alice
|
||
```
|
||
````
|
||
|
||
````markdown
|
||
```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
|
||
|
||
```markdown
|
||
<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
|
||
|
||
```markdown
|
||
Ein Wort mit <span style="color: var(--color-accent)">Akzentfarbe</span>
|
||
mitten im Satz, oder ein <br> für einen manuellen Zeilenumbruch.
|
||
```
|
||
|
||
### Eingebettete Inhalte
|
||
|
||
```markdown
|
||
<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:
|
||
|
||
```markdown
|
||
---
|
||
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.):
|
||
|
||
```markdown
|
||
<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:
|
||
|
||
```markdown
|
||
---
|
||
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
|
||
|
||
```markdown
|
||
---
|
||
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
|
||
```
|
||
|
||
<div style="font-size: var(--font-size-sm); color: var(--color-muted)">
|
||
Letzte Aktualisierung: 2026-07-08
|
||
</div>
|
||
```
|
||
|
||
Weitere lauffähige Beispiele findest du in [`examples/demo/`](../examples/demo/).
|