Die Markdown-Vorlage soll dabei helfen bessere README-Dateien zu schreiben. Eine gut geschriebene Dokumentation vermittelt Kompetenz und hilft dabei Code und Datenanalysen besser zu verstehen.
Dieses README baut auf den Ideen von Stephen Whitmore's Art of README auf.
Dieses Readme ist in Markdown geschrieben. Um es zu bearbeiten reicht ein einfacher Text-Editor wie Sublime Text. Um eine HTML-Vorschau zu erzeugen benötigt es allerdings ein Plugin wie sublimetext-markdown-preview. Eine Liste anderen Markdown-Editoren gibt es hier.
- Repository klonen
git clone https://... - README bearbeiten
subl README.md - Änderungen einchecken
git add README.mdund committengit commit -m "Update README"
Tipps, um semantische READMEs mit Markdown zu schreiben. Ein vollständige Dokumentation der Funktionen bietet das Markdown Cheatsheet.
Hervorhebungen lassen sich in Markdown folgendermaßen gestalten:
- Text fett:
**fett** - Text kursiv:
*fett*
Außerdem gibt es verschiedene Überschriften:
Die Überschriften unterscheiden sich jeweils durch die Anzahl der vorangestellten Rauten ## H2.
Markdown bietet die Möglichkeit verschiedene Aufzählungen anzulegen.
Unsortierte Aufzählungen mit vorangestellten Bindestrichen -:
- Listeneintrag
- anderer Listeneintrag
- noch ein Listeneintrag
Sortierte Aufzählung mit vorangestellten Zahlen 1.:
- Erster Listeneintrag
- Zweiter Listeneintrag
- Dritter Listeneintrag
Links bestehen jeweils aus einem Linktext und einer URL [Linktext](http://github.com/br-data).
Beispiel: Zur README-Vorlage
Bilder können nach dem gleichen Prinzip eingebunden werden. Einziger Unterschied ist das führende Ausrufezeichen 
Unformatierte Codefragmente können im Paragraphen mit Backticks this.function() angezeigt werden oder als ganze Code-Blöcke mit drei Backticks in der ersten und letzten Zeile. Für passendes Syntax-Highlighting muss in der ersten Zeile die Skriptsprache angegeben werden javascript.
Beispiel:
function add(a, b) {
return a+b
}
add(1, 2) // returns 3Manchmal funktioniert der Markdown-Renderer nicht. In diesem Fall hilft meistens ein Neustart des Text-Editors.
- Beispiel-Readme auf Englisch hinzufügen
- Einstellungen im Text-Editor ausführlicher beschreiben
- Philosophie: Art of README
- Markdown-Beispiele von Github Markdown und Markdown Cheatsheet