Markdown für technische Dokumentation

Die Formatierungsfrustration

Sie schreiben Dokumentation. Sie wollen eine einfache Aufzählungsliste. Sie verbringen 10 Minuten damit, mit der Formatierung eines Textverarbeitungsprogramms zu kämpfen.

Sie möchten ein Codebeispiel hinzufügen. Die Syntaxhervorhebung ist falsch. Die Schriftart ist falsch. Die Einrückung ist falsch.

Markdown löst dies. Sie schreiben in Klartext. Einfache Symbole steuern die Formatierung. Es funktioniert einfach.

Was ist Markdown?

Markdown ist eine leichtgewichtige Auszeichnungssprache. Sie schreiben in Klartext unter Verwendung einfacher Symbole zur Formatierungsangabe.

Es wurde 2004 von John Gruber erstellt. Das Ziel war Lesbarkeit: Ein Markdown-Dokument sollte unverändert als Klartext veröffentlicht werden können, ohne wie mit Tags oder Formatierungsanweisungen markiert auszusehen.

Heute ist Markdown überall. GitHub, Reddit, Stack Overflow, Notion und viele weitere Plattformen unterstützen es.

Grundlegende Markdown-Syntax

Hier sind die häufigsten Formatierungsoptionen:

Das Dokument strukturieren

Beginnen Sie mit einer H1 für den Titel, H2 für die Hauptabschnitte und H3 für Unterabschnitte. Überspringen Sie keine Ebenen: Ein Sprung von H2 auf H4 bricht das Inhaltsverzeichnis.

Die meisten Renderer erzeugen ein Inhaltsverzeichnis automatisch aus den Überschriften. Ich habe eine 4.000 Wörter lange API-Anleitung aus einer solchen Gliederung geplant; es dauerte zwanzig Minuten.

# Projektname
## Installation
### Über npm
## Konfiguration
### Umgebungsvariablen

• Eine H1 pro Dokument, reserviert für den Titel
• Konsistente Ebenen: H2 für Abschnitte, H3 für Unterabschnitte
• Beschreibende Überschriften, damit das Inhaltsverzeichnis selbsterklärend ist

Codeblöcke mit Sprachhinweis

Eingerückte Codeblöcke beginnen und enden mit drei Backticks. Fügen Sie die Sprache nach dem öffnenden Backtick hinzu, etwa ```js oder ```bash; die meisten Renderer färben die Syntax automatisch ein.

Der Sprachhinweis zählt auch ohne Färbung; einige Plattformen nutzen ihn für Linting oder einen Kopier-Button. Die Einrückung wird exakt übernommen, halten Sie den Quelltext also ordentlich.

```js
const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.update('Nachricht');
console.log(hash.digest('hex'));
```

• Jeden Codeblock schließen; ein offener Block verschluckt den Rest des Dokuments
• Vor Listen eine Leerzeile lassen
• Die Trennzeile der Tabelle direkt unter die Kopfzeile setzen

Tabellen, Hinweisboxen und Bilder

Tabellen stammen aus GitHub Flavored Markdown: eine Kopfzeile, eine Trennzeile aus Strichen und Datenzeilen. Doppelpunkte in der Trennzeile setzen linksbündig, zentriert oder rechtsbündig.

Hinweisboxen, die farbigen Kästen in vielen Doku-Systemen, sind kein Standard-Markdown. GitHub rendert `> [!NOTE]` und `> [!WARNING]`, aber prüfen Sie zuerst die Zielplattform.

Bilder nutzen die Link-Syntax mit vorangestelltem Ausrufezeichen: ![Alt-Text](pfad/zum/bild.png). Verwenden Sie beschreibenden Alt-Text und relative Pfade, damit Bilder einen Klon überstehen.

> [!NOTE]
> Dieses Feature benötigt Node.js 18 oder neuer.
| Ausgabe | Bytes |
| --- | ---: |
| sha256 | 32 |
| sha512 | 64 |

Vor der Veröffentlichung lokal ansehen

Renderer unterscheiden sich in kleinen Details, sehen Sie sich also die Ausgabe an. Fügen Sie das Dokument in die Markdown-Vorschau ein und prüfen Sie das Ergebnis, bevor es in ein Repository oder CMS wandert.

1. Das Dokument schreiben, eine Überschriftenebene nach der anderen.
2. Die Markdown-Vorschau öffnen und den Quelltext einfügen.
3. Denselben Quelltext auf der Zielplattform testen, denn Renderer unterscheiden sich.

Warum Markdown verwenden?

Markdown hat mehrere Vorteile gegenüber traditionellen Textverarbeitungsprogrammen:

• Portabel - Klartext funktioniert auf jedem Gerät, für immer
• Versionskontrolle-freundlich - Git kann Markdown-Dateien einfach vergleichen
• Schnell zu schreiben - Keine Maus benötigt, halten Sie Ihre Hände an der Tastatur
• Konvertiert zu allem - HTML, PDF, DOCX, Folien und mehr
• Zukunftssicher - Klartext wird nie veraltet
• Ablenkungsfrei - Konzentrieren Sie sich auf Inhalt, nicht auf Formatierung

Markdown-Varianten

Es gibt viele Variationen von Markdown, genannt 'Flavors'. Sie fügen Funktionen zur ursprünglichen Spezifikation hinzu.

GitHub Flavored Markdown (GFM) fügt Tabellen, Aufgabenlisten und Durchstreichung hinzu. Es ist die beliebteste Variante.

CommonMark ist eine standardisierte Version, die darauf abzielt, Mehrdeutigkeiten in der ursprünglichen Spezifikation zu klären.

MultiMarkdown fügt Fußnoten, Zitate und mathematische Formeln hinzu. Beliebt in akademischem Schreiben.

FAQ

Referenzen

• CommonMark Specification: https://spec.commonmark.org/
• GitHub Flavored Markdown Spec: https://github.github.com/gfm/
• RFC 7764 – Guidance on Markdown: https://www.rfc-editor.org/info/rfc7764/
• MDN – Markdown-Richtlinien: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
• Ursprüngliche Markdown-Syntax (John Gruber): https://daringfireball.net/projects/markdown/syntax