2026-07-15 20:14:07 +02:00

11 KiB

Raw Blame History

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. 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". 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

![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

> 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, 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.:

```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>

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

Letzte Aktualisierung: 2026-07-08

```

Weitere lauffähige Beispiele findest du in examples/demo/.

11 KiB Raw Blame History Unescape Escape