GitHub: Seiten mit Markdown gestalten
GitHub-Projekte sind nur dann erfolgsversprechend, wenn Sie es auch ordentlich beschreiben - und zwar im ansprechenden Layout mit Markdown.
- Cornelia Möhring
Wenn Sie Ihr GitHub-Projekt dokumentieren, müssen Sie nicht auf schnöden, einheitlichen Fließtext setzen. Mit dem teils hauseigenen Markdown lassen sich Liesmich-Dateien und Dokumentation richtig gut layouten.
- Was ist Markdown?
- Überschriften und Auszeichnungen
- Links und Bilder
- Listen und Tabellen
- Emojis und Sonstiges
Was ist Markdown?
Markdown ist im Grunde eine ziemlich simple Angelegenheit, eine Auszeichnungssprache. Genau wie HTML: HTML war mal eine "einfache" Möglichkeit, Webseiten zu gestalten - einfach im Vergleich zu Programmiersprachen. Aber letztlich ist die HTML-Syntax nicht für längere Fließtexte geeignet. Ständig warten irgendwelche Klammern, Anführungszeichen und bestimmte Schlagwörter darauf, zeichengenau gesetzt zu werden. Wenn Sie zum Beispiel das Wort "Fett" mal fett schreiben wollen: <b>fett</b>
Markdown vereinfacht die Angelegenheit deutlich, ein simples **fett** wird auf Markdown-fähigen Seiten genauso dargestellt wie die HTML-Variante. Genauer gesagt: Sie wird in die HTML-Variante übersetzt. Die Markdown-Auszeichnungen sind deutlich einfacher zu merken und vor allem zu tippen.
Nun gibt es nicht bloß die eine Ausprägung von Markdown, auch wenn die meisten Elemente standardisiert sind. Github bietet jedenfalls einige Sondermöglichkeiten darüber hinaus, beispielsweise um Github-Nutzer mit einer hervorgehobenen Formatierung erwähnen zu können oder um Code und Befehle klar darzustellen.
Im Folgenden sehen Sie, welche Elemente Sie wie einsetzen, um eine hübsch formatierte Readme-Datei zu erstellen:
- Überschriften
- Textauszeichnung (fett, kursiv, durchgestrichen)
- Links
- Bilder
- Listen (ungeordnet, nummeriert, ToDo)
- Tabellen
- Emojis
Außen vor bleiben Referenzen auf Nutzer (@nutzer) und Pull Requests, da diese in normalen Dateien nicht funktionieren, sondern nur in Beschreibungen und Kommentaren von Pull Requests und Issues.
Überschriften und Auszeichnungen
Wenn Sie in GitHub ein Projekt anlegen, bekommen Sie auch gleich eine vorgefertigte, leere Datei "LIESMICH.md" - wobei das "md" natürlich für Markdown steht. Öffnen Sie den Editor für die Datei und beginnen Sie zum Beispiel mit den Überschriften, um den Artikel zu strukturieren:
# Mein Projekt
## Installation
### Windows
### Linux
## Nutzung
### Beispiele
## Fehlerbehebung
## Lizenz
Eine Raute steht für eine Überschrift erster Ordnung, zwei bis sechs Rauten entsprechend für untergeordnete Überschriften. Zum Testen können Sie sofort auf den Tab "Preview" tippen, schon sehen Sie Ihr erstes gerendertes Markdown.
Es folgt gemeinhin ein wenig Fließtext zum Beschreiben:
# Mein Projekt
In "Mein Projekt" lässt sich Text sowohl *kursiv* als auch **fett** als auch ~~durchgestrichen~~ darstellen.
In diesem neuen Absatz sehen Sie ein Beispiel für Code: Tippen Sie `echo Hallo`.
Hier sehen Sie gleich mehrere neue Auszeichnungen, die jeweils den Effekt haben, der in den Sternchen oder Tilden steht. Ein neuer Absatz wird schlicht und ergreifend durch eine Leerzeile erzielt - wie Sie es aus Texteditoren kennen. Wichtig ist die Auszeichnung von Code: Bei `echo Hallo` handelt es sich nicht um das einfache Anführungszeichen, sondern um einen Gravis, besser bekannt als accent grave oder in der Programmierung als Backtick. Gemeint ist das selten benutzte Zeichen links neben der Taste [ZURÜCK] auf der Tastatur, die über [UMSCHALT] + [´] + [LEERTASTE] entsteht - ohne Leertaste würde der Backtick als accent grave über einen Buchstaben gesetzt.
Ganze Blöcke von Code können Sie in dreifache Backticks setzen:
```
echo Hallo
echo World
```
Alternativ ließen sich Code-Blöcke auch mit vier Leerzeichen einrücken, was Programmiersyntax entliehen ist. Letztlich ist so ein Code-Block nur eine Sonderform des Zitats. Normale Zitate sind noch einfacher:
Ein berühmter Skripter sagte:
> Hallo Welt
Links und Bilder
Was aber ist hübscher Text ohne Links und Bilder? Warum beide zusammenfallen? Letztlich sind Bilder nur eine Sonderform des Links. Links schreiben Sie in Markdown über ein Klammernpaar: In eckigen Klammern steht der Text, in runden Klammern dahinter der Link:
[Ein Link zur Wikipedia](https://www.wikipedia.de)
Vollständige URLs wie https://www.wikipedia.de werden zudem automatisch in anklickbare Links umgewandelt.
Bei Bildern verhält es sich fast genauso, allerdings ist der vordere Text in eckigen Klammern der Alt-Text des Bilds und es steht ein Ausrufezeichen davor:
Achten Sie hier mal auf den Inhalt der runden Klammer: Es handelt sich hier um einen relativen Link auf ein Bild im Verzeichnis "bilder". Wie Sie es vielleicht aus dem Terminal kennen, ließe sich hier zum Beispiel auch auf einen Ordner zwei Ebenen weiter oben verlinken: "../../testdateien/meinedatei.txt".
Listen und Tabellen
Häufig werden Sie Informationen als Listen anbieten - was erfreulich einfach ist, hier etwa in einer geordneten Liste:
1. Installieren Sie das Programm
1. Unter Linux:
1. Ubuntu:
1. Debian:
1. Unter Windows
1. Nutzen Sie das Programm
1. Unter Linux:
1. ...
Sie können tatsächlich überall "1." nutzen, die Nummerierung wird automatisch gesetzt. Für eine ungeordnete Liste verwenden Sie "-" oder "*".
Dennoch ist das etwas frickelig: Die Punkte müssen jeweils genau unter dem ersten Buchstaben des übergeordneten Punkts beginnen. Und wenn Sie keine verschachtelte, sondern eine ToDo-Liste erstellen wollen.
Achtung: Damit die folgenden Listeneinträge für Sie funktionieren, müssen Sie jeweils den Punkt (.) entfernen, den wir hineingesetzt haben. Dieser dient lediglich dazu, dass Ihnen die Einträge hier im Markdown-Format angezeigt werden und nicht schon automatisch als (abgehakte) ToDo-Liste erscheinen.
- [.x] Readme anlegen
- [.x] Erste Formatierungen lernen
- [.] Readme vervollständigen
- [.] Readme veröffentlichen
Sie ahnen es vielleicht schon: Hier werden vor den Listeneinträgen Kästchen gesetzt, die die Aufgaben mit Häkchen als erledigt ([.x]) oder ohne Häkchen als offen ([.]) darstellen.
Die Königsdisziplin in HTML ist aber die Tabelle - Tabellen sind immer fehleranfällig. Markdown kann das viel viel besser! Ein simples Beispiel mit Spaltenüberschriften, zwei Spalten und drei Zeilen:
Programmaufruf | Funktion
-------------- | --------
foobar -v | Erweiterte Informationen
foobar -t | Programm nur testen
foobar -vt | Programm mit allen Optionen ausführen
Das Prinzip: Spalten werden per Pipe-Sympol, also dem senkrechten Strich getrennt. In der ersten Zeile stehen die Überschriften, die zweite Zeile trennt diese vom eigentlichen Tabelleninhalt ab. Es folgen alle Tabelleneinträge, wieder getrennt durch Pipes. Im Gegensatz zu Listen müssen diese hier natürlich nicht an bestimmten Stellen stehen, die Länge jedes Texts in jeder Zelle ist beliebig.
Emojis und Sonstiges
Auf GitHub wird vor allem viel kommuniziert - und das geht heutzutage nicht ohne Emojis, die Sie ganz trivial per ":smile:", ":angry:" und so weiter setzen können. Die komplette Liste finden Sie hier: https://www.webfx.com/tools/emoji-cheat-sheet/
Wie bereits erwähnt, können Sie in einigen Bereichen von GitHub noch Referenzen auf Nutzer und Issues setzen - nicht aber in einer Readme-Datei. Die Syntax ist wieder ganz simpel:
@nutzer_123 bitte schau Dir mal Issue #33 an - Danke :smile:
Aus "@nutzer_123" und "#33" würden hier wiederum schickere Formatierungen gerendert.
Damit Sie nun auch mal das Ergebnis der Arbeit sehen, hier die erstellte LIESMICH.md mit allen Beispielen als Screenshot:
Hier erkennen Sie natürlich nur das Gesamtlayout. Die aufgesetzte Datei können Sie sich hier bei GitHub anschauen.
(como)
