Markdown-Grundlagen für Android: Überschriften, Listen und Links

Markdown ist eine schlanke Auszeichnungssprache, die du in der Android-Welt überall antriffst: README auf GitHub, Release-Notes im Play Console, Architecture-Decision-Records im Repo, Issue-Templates in Jira oder GitLab, Kommentare in Pull-Requests. Wer Markdown sicher beherrscht, schreibt schneller verständliche Notizen, baut lesbare Doku neben dem Code und macht sich beim Onboarding neuer Teammitglieder sofort nützlich. In diesem Artikel ordnest du die Grundlagen ein – mit Fokus auf Überschriften, Listen und Links, also genau die Bausteine, die du in den meisten Texten brauchst.

Was ist das?

Markdown ist ein Plain-Text-Format, das mit wenigen Sonderzeichen formatierte Dokumente erzeugt. John Gruber entwickelte es 2004 als Brücke zwischen HTML-Output und einem für Menschen gut lesbaren Quelltext. Heute kommt fast jedes Tool im Android-Alltag damit klar: GitHub und GitLab rendern jede README.md automatisch, Android Studio zeigt Markdown direkt im Editor mit Vorschau an, und auch Plattformen wie StackOverflow, Reddit, Discord oder Notion bauen auf einer Markdown-Variante auf.

Für dich als Lernende oder Lernender bedeutet das: Du beschreibst Konzepte, Tickets oder Architekturentscheidungen einmal sauber in einer .md-Datei und musst dich nicht in HTML-Tags oder ein WYSIWYG-Tool eingrooven. Im Repo lebt der Text neben dem Kotlin-Code, wandert durch dieselbe Pull-Request-Pipeline und lässt sich genauso reviewen wie eine MainActivity.kt. Das spart Kontextwechsel und macht Wissen langlebig. Eine gute Markdown-Datei überlebt Tool-Wechsel, weil sie reiner Text bleibt – im schlimmsten Fall kannst du sie auch in einem nackten Terminal lesen.

Es gibt nicht „das eine” Markdown, sondern verschiedene Dialekte. CommonMark ist der Versuch einer Standardisierung, GitHub Flavored Markdown (GFM) erweitert ihn um Tabellen, Task-Listen und Code-Highlighting. Für Android-Projekte auf GitHub ist GFM die übliche Wahl.

Wie funktioniert es?

Markdown ersetzt Auszeichnung durch lesbare Zeichen. Eine Überschrift beginnt mit einem oder mehreren Rauten (#), eine ungeordnete Liste mit - oder *, eine geordnete Liste mit 1., ein Link sieht aus wie [Beschriftung](URL). Jeder Renderer übersetzt diese Zeichen in HTML – aus ## Setup wird <h2>Setup</h2>, aus [Compose](https://developer.android.com/jetpack/compose) ein anklickbarer Verweis.

Überschriften

Du nutzt sie, um Dokumente zu strukturieren. Eine # Hauptüberschrift pro Datei, dann ## Abschnitt und ### Unterabschnitt. Springe keine Ebenen: Auf ## folgt entweder ## oder ###, niemals direkt ####. Dieser Hierarchie-Sprung killt nicht nur Screenreader, sondern auch generierte Inhaltsverzeichnisse vieler Doc-Tools wie Dokka, MkDocs oder Docusaurus. Achte außerdem auf eine Leerzeile vor und nach jeder Überschrift; sonst rendert dein ## Setup mancherorts als Fließtext mit Rauten.

Listen

Ungeordnete Listen markierst du mit -, * oder +. Wähle eines davon und bleib dabei – Konsistenz schlägt Geschmack. Geordnete Listen schreibst du mit 1., 2., 3. oder einfach mit 1. für jede Zeile, weil der Renderer automatisch durchnummeriert. Verschachtelte Listen brauchen genau zwei oder vier Leerzeichen Einrückung pro Ebene; ein Tab funktioniert je nach Renderer unterschiedlich, also vermeide ihn. Mische außerdem nicht ungeordnete und geordnete Listen wild durcheinander, sonst wird die Hierarchie unklar.

Links

Inline-Links nutzen die Form [Text](URL). Für längere Dokumente mit vielen externen Verweisen lohnen sich Reference-Links: [Compose Docs][1] plus ganz unten [1]: https://developer.android.com/jetpack/compose. Das hält den Fließtext schmal. Relative Pfade wie [Architektur](docs/architecture.md) zeigen auf andere Dateien im Repo und überleben einen Repository-Umzug, solange die Ordnerstruktur stimmt. Anker funktionieren mit #, etwa [zum Setup](#setup). GitHub erzeugt Anker automatisch aus den Überschriften – kleinschreiben und Leerzeichen durch Bindestriche ersetzen.

In der Praxis

Stell dir vor, du legst ein neues Modul feature-login in einer Multi-Module-Android-App an. Eine knappe README.md direkt im Modulordner hilft jedem Reviewer, der zum ersten Mal in deinen Code schaut. Ein praktisches Skelett:

# feature-login

Login-Flow auf Basis von Jetpack Compose und Hilt.

## Aufbau

- `LoginScreen.kt` – Compose-Einstiegspunkt
- `LoginViewModel.kt` – State-Holder mit `StateFlow`
- `LoginRepository.kt` – Datenzugriff über Retrofit

## Setup

1. Modul in `settings.gradle.kts` registrieren
2. In der App-`build.gradle.kts` per `implementation(project(":feature-login"))` einbinden
3. Hilt-Module via `@InstallIn(SingletonComponent::class)` bereitstellen

## Weiterführend

- [Android Basics with Compose](https://developer.android.com/courses/android-basics-compose/course)
- [Application Fundamentals](https://developer.android.com/guide/components/fundamentals)

Diese Datei rendert sauber in Android Studio, GitHub und in jedem Wiki-Tool. Du brauchst keinen weiteren Build-Schritt. Eine gute Faustregel: Schreibe deine README so, dass jemand mit Kotlin-Vorkenntnissen das Modul in unter zwei Minuten in seine App einbinden kann. Wenn du nach dem Schreiben noch zwei Sätze mündliche Erklärung brauchst, ist die README zu knapp.

Typische Stolperfallen

• Leerzeilen vergessen: Markdown braucht eine Leerzeile vor und nach Überschriften, Code-Blöcken und Listen. Ohne Leerzeile rendert dein ## Setup plötzlich als Fließtext.
• Falsche Code-Sprache: Code-Blöcke startest du mit drei Backticks plus Sprache, etwa kotlin, xml, kts oder bash. Dann färbt der Renderer das Snippet richtig ein. Ein leerer Backtick-Block ohne Sprache verliert das Highlighting.
• Hartes Umbrechen: Ein einzelner Zeilenumbruch im Quelltext erzeugt im Output keinen Absatz. Du brauchst eine echte Leerzeile dazwischen, sonst klebt dein Text zu einem Block zusammen.
• Linktext „hier klicken”: Schreibe sprechende Linktexte. Statt [hier klicken](https://...) lieber [Compose Codelab](https://...). Das hilft Screenreadern und Suchmaschinen und verbessert die Lesbarkeit von Pull-Request-Beschreibungen.
• Zu tiefe Verschachtelung: Wenn deine Liste vier Ebenen tief geht, ist sie meist eine Tabelle oder ein eigenes Unterkapitel.

Fazit

Markdown ist kein Selbstzweck, sondern ein Werkzeug für lesbare Dokumentation neben deinem Android-Code. Wenn du Überschriften, Listen und Links sauber anwendest, schreibst du README-Dateien, ADRs und Lernnotizen, die andere Entwicklerinnen und Entwickler tatsächlich lesen. Übe das, indem du heute noch eine bestehende README in einem Übungsprojekt überarbeitest: Prüfe die Hierarchie der Überschriften, ersetze nichtssagende Linktexte und füge ein klares Setup-Kapitel hinzu. Lass dir das Ergebnis im Pull-Request reviewen – nicht nur den Code, sondern auch die Dokumentation. Schreibe ein Feedback wie „die Überschriftshierarchie springt von H2 zu H4” genauso selbstverständlich wie ein Kommentar zu fehlender Null-Sicherheit. Markdown wird dich durch deine gesamte Android-Karriere begleiten, also lohnt es sich, die Grundlagen jetzt zu festigen und in jedem neuen Repo bewusst anzuwenden.