Überschriften in Markdown

Überschriften sind das Skelett eines Dokuments. In Markdown kosten sie ein einziges Zeichen: ein # am Zeilenanfang, einmal pro Ebene wiederholt. Alles Weitere — die Gliederung, die daraus entsteht, das Inhaltsverzeichnis, die Ankerlinks — bekommst du geschenkt, sobald die Ebenen stimmen.

Ändere unten die Anzahl der # und sieh zu, wie die Größen springen:

# Der Dokumenttitel

Ein einleitender Absatz.

## Ein größerer Abschnitt

### Ein Unterabschnitt

#### Ein kleinerer Punkt

Text unter einer Überschrift gehört zu ihr.

Die sechs Ebenen

# bis ###### werden zu <h1> bis <h6>. Eine siebte Ebene gibt es nicht; ein siebtes # erscheint als gewöhnlicher Text.

# Überschrift Ebene 1
## Überschrift Ebene 2
### Überschrift Ebene 3
#### Überschrift Ebene 4
##### Überschrift Ebene 5
###### Überschrift Ebene 6

In der Praxis wirst du drei benutzen. Ein Dokument, das bis ##### reicht, ist meistens ein Dokument, das in zwei zerfallen möchte.

Das Leerzeichen ist nicht optional

#Überschrift ist ein Absatz, der mit einer Raute beginnt. # Überschrift ist eine Überschrift. Setz immer ein Leerzeichen hinter das letzte #.

Das ist der mit Abstand häufigste Grund dafür, dass eine Überschrift als reiner Text erscheint, und man sieht es erst in der Vorschau.

Ein # pro Dokument

Nimm ein einzelnes # und behandle es als Titel. Alles darunter gliederst du mit ## und ###.

Zwei Gründe, und nur einer davon hat mit Suchmaschinen zu tun:

• Für Lesende und Screenreader sind die Ebenen eine Gliederung, durch die man navigiert. Von # gleich auf ### zu springen oder drei #-Überschriften zu haben macht diese Gliederung sinnlos.
• Für Suchmaschinen ist die <h1> ein starkes Signal dafür, worum es auf der Seite geht. Mehrere davon verdünnen es.

Überspring auch auf dem Weg nach unten keine Ebene: ein ### gehört unter ein ##, nicht direkt unter ein #.

Setext-Überschriften

Es gibt eine ältere Syntax, der du in Jahre alten Dateien begegnest — der Text wird mit = oder - unterstrichen:

Der Dokumenttitel
=================

Ein größerer Abschnitt
----------------------

= macht eine <h1>, - eine <h2>. Mehr kann sie nicht, und genau daran ist sie verblasst: Eine dritte Ebene lässt sich damit nicht ausdrücken. Erkenn sie, wenn du sie siehst, und schreib selbst #.

Achtung, Falle: Eine Zeile aus Bindestrichen direkt unter einem Absatz macht diesen Absatz zur Überschrift, statt eine Trennlinie zu zeichnen. Wenn du einen Trenner willst, lass eine Leerzeile darüber.

Aus Überschriften werden Ankerlinks

Die meisten Renderer — GitHub, Generatoren für statische Seiten, Dokumentationswerkzeuge — geben jeder Überschrift eine id, abgeleitet aus ihrem Text, sodass man direkt auf einen Abschnitt verlinken kann:

Siehe den [Abschnitt über Ankerlinks](#aus-uberschriften-werden-ankerlinks).

Die Regel ist fast immer dieselbe: Text kleinschreiben, Leerzeichen durch Bindestriche ersetzen, Satzzeichen weglassen. Aus ## Die sechs Ebenen wird #die-sechs-ebenen. Teilen sich zwei Überschriften denselben Text, hängt die zweite meist ein -1 an.

Genau das macht ein Inhaltsverzeichnis möglich — auch das auf dieser Seite. Mehr zum Verlinken in der Anleitung zu Links.

Häufige Fehler

Kein Leerzeichen nach dem #. Die Zeile erscheint als Absatz. Prüf das zuerst, wenn eine Überschrift ausbleibt.

Keine Leerzeile um die Überschrift. Manche Parser verlangen eine Leerzeile vor einer Überschrift, besonders direkt nach einem Absatz. Eine oben und eine unten funktioniert überall.

Rauten am Ende. ## Abschnitt ## ist erlaubt — die schließenden Rauten werden entfernt —, aber es ist Lärm. Lass sie weg.

Fett statt Überschrift. Eine Zeile **Abschnittstitel** sieht aus wie eine Überschrift und ist keine: kein Eintrag in der Gliederung, kein Anker, keine Struktur. Screenreader können nicht danach navigieren, und Suchmaschinen lesen sie nicht als Abschnitt.

Mehrere # in einer Datei. Teil das Dokument, oder stuf alle außer dem ersten herunter.

Häufige Fragen

Wie viele Überschriftenebenen kennt Markdown?

Sechs, von # für <h1> bis ###### für <h6>. Ein siebtes # ist keine Überschrift und erscheint als Text. Die meisten Dokumente brauchen nur drei Ebenen.

Warum funktioniert meine Markdown-Überschrift nicht?

Fast immer fehlt das Leerzeichen zwischen # und Text. #Titel ist ein Absatz, # Titel eine Überschrift. Der zweithäufigste Grund ist die fehlende Leerzeile zwischen dem vorherigen Absatz und der Überschrift.

Sollte ein Markdown-Dokument nur eine H1 haben?

Ja, in aller Regel. Ein # dient als Dokumenttitel, alles andere hängt sich mit ## und ### darunter. Das hält die Gliederung für Screenreader sinnvoll und das Hauptthema der Seite für Suchmaschinen eindeutig.

Wie verlinke ich auf eine Überschrift in Markdown?

Über den erzeugten Anker: Text kleinschreiben, Leerzeichen durch Bindestriche ersetzen, Satzzeichen entfernen, dann mit # darauf verlinken. Aus ## Erste Schritte wird [hin](#erste-schritte). Die genaue Regel unterscheidet sich zwischen Renderern leicht.

Was ist der Unterschied zwischen #-Überschriften und unterstrichenen Überschriften?

Für die ersten beiden Ebenen keiner. Ein = unter einer Zeile macht eine <h1>, ein - eine <h2>; dieser ältere Setext-Stil kann die Ebenen drei bis sechs nicht ausdrücken, deshalb hat die #-Syntax ihn fast überall abgelöst.