So erstellst du in Markdown einen aufklappbaren Bereich:die Tags details und summary.

Die Syntax

Ein aufklappbarer Bereich ist ein einfaches HTML-Element: <details> ist der Container, <summary> die anklickbare Zeile, und alles nach dem summary bleibt verborgen, bis der Leser klickt. Das Öffnen und Schließen übernimmt der Browser (oder die Web-Ansicht der Markdown-App), du brauchst also kein Skript und keine zusätzliche Syntax.

<details>
<summary>Click to expand</summary>

Hidden text goes here.

</details>

Geschlossen sieht der Leser ein kleines Dreieck und die Worte Click to expand. Ein Klick dreht das Dreieck und zeigt den Text. Dasselbe Muster nutzen GitHub-READMEs, Issues und Pull-Request-Kommentare für lange Logs und optionale Hinweise.

Die Regel mit der Leerzeile

Markdown in einem <details>-Block wird nur verarbeitet, wenn es durch eine Leerzeile von den HTML-Tags getrennt ist. So liest CommonMark einen HTML-Block: Er reicht bis zur nächsten Leerzeile und wird als rohes HTML durchgereicht. Ohne die Leerzeile bleiben dein **bold** und deine Liste wörtliche Zeichen.

<details>
<summary>Broken</summary>
- this list is not turned into a list
</details>

<details>
<summary>Works</summary>

- this one is a list

</details>

Setze eine Leerzeile nach </summary> und eine weitere vor </details>. Auch die summary-Zeile selbst ist HTML, nimm dort also <b>bold</b> oder <code>code</code>, kein Markdown.

Standardmäßig geöffnet

Füge das Attribut open hinzu, damit der Bereich aufgeklappt startet. Der Leser kann ihn weiterhin zuklappen.

<details open>
<summary>Prerequisites</summary>

Node 20 or later.

</details>

Setze es sparsam ein: Auf einer Seite, bei der alles geöffnet startet, gibt es keinen Grund zum Einklappen, und auf einer Seite, bei der alles geschlossen startet, bleiben die nützlichen Teile verborgen. Eine gute Regel: Lass die Antwort sichtbar und klappe die Belege ein, etwa lange Ausgaben, eine vollständige Konfiguration oder eine Liste von Randfällen.

Beispiele: Code, Verschachtelung und eine lange Liste

Ein Codeblock in einem Bereich braucht seine Leerzeilen wie alles andere in Markdown:

<details>
<summary>Full config</summary>

```json
{ "retries": 3, "timeout": 30 }
```

</details>

Bereiche lassen sich verschachteln. Rücke den inneren ein, wenn du magst, aber auf die Leerzeilen kommt es an:

<details>
<summary>Troubleshooting</summary>

<details>
<summary>The app does not start</summary>

Check the log in the console.

</details>

</details>

So sieht ein Bereich für den Leser aus, geschlossen bis zum Klick:

Show the full log

Everything here is hidden until the title is clicked.

Wann ein aufklappbarer Bereich sinnvoll ist

Einklappen lohnt sich, wenn der Leser die Aufgabe erledigen kann, ohne den Bereich zu öffnen. Gute Kandidaten sind lange Befehlsausgaben, eine vollständige Konfigurationsdatei, eine Tabelle mit Optionen, ein Changelog alter Versionen oder eine Liste von Schritten zur Fehlersuche bei seltenen Problemen. Ein kurzer Hinweis, den die meisten Leser brauchen, sollte sichtbar bleiben.

Ein Bereich ist auch eine saubere Möglichkeit, lange eingefügte Logs in einen Fehlerbericht oder eine Pull-Request-Beschreibung zu setzen: Der Leser sieht zuerst die Zusammenfassung dessen, was schiefging, und öffnet das Log nur bei Bedarf. Gib dem summary einen konkreten Titel, etwa Build log (412 lines), damit der Leser vor dem Klick weiß, was darin steht.

Häufige Fehler

• Keine Leerzeile. Der Text darin zeigt rohes Markdown. Füge eine Leerzeile nach dem summary und vor dem schließenden Tag ein.
• Markdown im summary. Nimm dort HTML-Tags.
• Ein fehlendes schließendes Tag. Alles darunter bleibt im Bereich.
• Eine App, die HTML entfernt. Manche Renderer entfernen Tags, denen sie nicht trauen, und dann ist der Text einfach sichtbar. Muss der Bereich überall funktionieren, teste ihn dort, wo er gelesen wird.
• Überschriften im summary. Die Überschrift erscheint in der Gliederung der meisten Apps nicht. Setze die Überschrift stattdessen über den Bereich.

Eingeklappter Text steht weiterhin in der Datei, Suche und Diffs sehen ihn also, ein Leser, der nie klickt, aber nicht. Verstecke nichts Wesentliches, etwa eine Warnung.

So sieht man es in Aktion

Um einen Bereich zu prüfen, öffne die Datei in einem Reader, der HTML rendert. DotMD zeigt <details> als Bereich, der sich per Klick öffnet, mit formatiertem Markdown darin, und in DotMD Editor schreibt Insert → Collapsible Section die Tags für dich. Lesen ist kostenlos.

Fragen zu aufklappbaren Bereichen in Markdown

Weitere Fragen