Portal:Markdown
Der Markdown-Lernpfad bringt erfahrene Entwicklerinnen und Entwickler Schritt für Schritt dazu, Markdown nicht mehr „aus dem Bauch heraus", sondern wirklich zu verstehen – CommonMark-Grundsyntax, GitHub Flavored Markdown (GFM), Frontmatter-Konventionen für Static-Site-Generatoren und Team-Tooling (`markdownlint`, Prettier, Keep a Changelog, GitHub-Vorlagen). Anders als die übrigen Geschwisterbücher ist dieses Buch an keinen Editor und an kein KI-Werkzeug gebunden – jede Übung funktioniert in jedem Texteditor und direkt im Browser. Durchgehendes Projekt ist wieder Harborlight und Team Driftline, mit Priya Nair (Tech Lead) als Hauptfigur, die uneinheitliche Dokumentation im Team konsistent machen will.
Der Lernpfad in vier Stufen
🟢 L1 – Grundlagen: Markdown lesen und schreiben, wie es gemeint ist
Blocksyntax-Grundprinzip, Überschriften, Betonung, Escaping, Listen, Links, Bilder, Codeblöcke.
| Nr. | Kapitel | Das lernst du | Status |
|---|---|---|---|
| 1 | Warum Markdown lernen, obwohl man's "schon kennt" | CommonMark vs. GitHub Flavored Markdown, warum „ein" Markdown nicht existiert | – |
| 2 | Blocksyntax: Absätze und Überschriften | Leerzeile trennt Blöcke, weicher vs. erzwungener Umbruch, ATX vs. Setext | – |
| 3 | Betonung und Escaping | `_` respektiert Wortgrenzen, `*` nicht; Sonderzeichen per Backslash escapen | – |
| 4 | Listen | Verschachtelung über relative Einrückung, straffe vs. lose Listen | – |
| 5 | Links und Bilder | Inline- vs. Referenzstil, Alt-Text als Pflicht, nicht als Kür | – |
| 6 | Codeblöcke | Inline-Code, indentierte vs. eingezäunte Codeblöcke, Sprachangabe | – |
🟡 L2 – Fortgeschritten: GitHub Flavored Markdown und Rendering-Unterschiede
Tabellen, Blockquotes, GFM-Erweiterungen, eingebettetes HTML, Renderer-Vergleich, Frontmatter.
| Nr. | Kapitel | Das lernst du | Status |
|---|---|---|---|
| 7 | Tabellen | GFM-Syntax, Ausrichtung, Pipe-Escaping – Ursache für mdBooks „unclosed HTML tag" | – |
| 8 | Blockquotes | Verschachtelung mit `>`, „lazy continuation" vs. explizite Markierung | – |
| 9 | GFM-Erweiterungen: Task Lists, Strikethrough, Autolinks | `- [ ]`/`- [x]`, `~~Text~~`, automatische URL-Verlinkung | – |
| 10 | Eingebettetes HTML | CommonMark reicht HTML durch, GitHub sanitisiert aus Sicherheitsgründen | – |
| 11 | CommonMark vs. GFM vs. mdBook | Spezifikation ist nicht Implementierung, am eigenen Buch demonstriert | – |
| 12 | Frontmatter | YAML-Metadaten für Jekyll/Hugo und GitHub-Issue-Vorlagen – kein mdBook-Feature | – |
🟠 L3 – Profi: Konsistenz und Team-Tooling
`markdownlint`, Prettier, CHANGELOG.md, GitHub-PR-/Issue-Vorlagen.
| Nr. | Kapitel | Das lernst du | Status |
|---|---|---|---|
| 13 | markdownlint | `markdownlint-cli2`, benannte Regeln, bewusste Ausnahmen dokumentieren | – |
| 14 | Automatisch formatieren mit Prettier | `proseWrap`, warum Formatierer und Linter sich ergänzen statt konkurrieren | – |
| 15 | CHANGELOG.md nach Keep a Changelog | Nutzerperspektive statt Commit-Historie, `Unreleased`, sechs Kategorien | – |
| 16 | GitHub-Vorlagen: PR- und Issue-Templates | `.github/PULL_REQUEST_TEMPLATE.md`, `.github/ISSUE_TEMPLATE/`, Issue Forms | – |
🔴 L4 – Ausblick, Grenzen
Ehrliche Grenzen von Markdown als Format.
| Nr. | Kapitel | Das lernst du | Status |
|---|---|---|---|
| 17 | Grenzen von Markdown und Ausblick | Keine Include-Logik, uneinheitliche Erweiterungen, wann ein anderes Werkzeug passt | – |