# 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.** Jede `.md`-Datei in dem Ordner, den du an
  `slidewalk` übergibst, wird 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
![Alt-Text](./bild.png)
```

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
`![Alt-Text](img/bild.png)`. 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>
```

## 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/).