├── .gitignore ├── LICENSE ├── README.md └── README.template.md /.gitignore: -------------------------------------------------------------------------------- 1 | # Passwords and tokes 2 | keys.production.js 3 | keys.stage.js 4 | keys.development.js 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Bayerischer Rundfunk 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Open Source bei BR Data 2 | 3 | Ein paar Empfehlungen zum Veröffentlichen von bestehenden Projekten auf Github. Grundsätzlich versuchen wir, alle Projekte zu veröffentlichen, die es unseren Nutzern ermöglichen, Rechercheweg und Datenanalyse hinter einer Geschichte zu verstehen und zu verifizieren (Transparenz). Wir sind bereit, zu unseren Fehlern zu stehen und sie gegebenenfalls auszubessern. Im Idealfall können die von uns entwickelten Programme und Analysen von der Datenjournalismus-Community weiter genutzt und verbessert werden. 4 | 5 | *„Open Source ist kein Dogma, sondern eine partizipative Kultur der Offenheit und des Teiles. Denn am Ende konkurrieren wir (Journalisten) nicht um das beste Werkzeug, sondern um die beste Geschichte.“* 6 | 7 | ## Inhalt 8 | 9 | - [Unterschiedliche Projektarten](#unterschiedliche-projektarten) 10 | - [Zielgruppe definieren](#zielgruppe-definieren) 11 | - [Deutsch oder Englisch?](#deutsch-oder-englisch) 12 | - [Projekt benennen](#projekt-benennen) 13 | - [README schreiben](#readme-schreiben) 14 | - [Dokumentation und Kommentare](#dokumentation-und-kommentare) 15 | - [Commit-Messages](#commit-messages) 16 | - [Große Dateien vermeiden](#große-dateien-vermeiden) 17 | - [Passwörter entfernen](#passwörter-entfernen) 18 | - [Badges](#badges-hinzufügen) 19 | - [Lizenz hinzufügen](#lizenz-hinzufügen) 20 | - [Einstellungen anpassen](#einstellungen-anpassen) 21 | - [Projekt veröffentlichen](#projekt-veröffentlichen) 22 | - [Lokales Projekt anpassen](#lokales-projekt-anpassen) 23 | - [Gute Beispiele](#gute-beispiele) 24 | - [Kontakt](#kontakt) 25 | 26 | ## Unterschiedliche Projektarten 27 | 28 | Verschieden Projekte stellen unterschiedliche Anforderungen an die Veröffentlichung. Oftmals überschneiden sich die Projektarten und lassen sich auch in einem Repository zusammenzufassen: 29 | 30 | - **Datenanalysen:** Bei Datenanalysen geht es vor allem darum, die einzelnen Schritte der Analyse transparent und reproduzierbar gestalten. 31 | - **Datensätze:** Es sollten vor allem Datensätze veröffentlicht werden, die anderweitig schwer zu bekommen sind. Zum Beispiel Datensätze, die von einer Behördenseite befreit wurden (z.B. durch einen Scraper). Wichtig: Urheberrechte abklären. 32 | - **interaktive Grafiken:** Auch interaktive Grafiken und Anwendungen, welche man auf ein anderes Themen anwenden könnte und die aufwändig erstellt wurden, sollten veröffentlicht werden. Beispiel: Wahlkarten, Netzwerk-Visualisierungen. 33 | - **Tools:** Allgemeine Werkzeuge, die bei einem bestimmten, verallgemeinerbaren, Workflow helfen. Beispiel: PDFs herunterladen, in Text umwandeln, in eine Datenbank importieren. Dabei geht es vor allem darum, häufige Aufgaben zu automatisieren. 34 | - **(Web-)Anwendungen:** Größere, aufwendige Software-Projekte, die einen verallgemeinerbaren Nutzen haben. 35 | 36 | ## Zielgruppe definieren 37 | 38 | Vor allem für das Readme und die Dokumentation ist es wichtig, sich zu überlegen, für wen man eigentlich schreibt. Generell hilft es immer, von sich selbst in zwei Jahren, oder einem Kollegen, der noch nichts mit dem Projekt zu tun hatte, auszugehen. Die Person beherrscht zwar die Grundlagen der Programmierung oder Datenanalyse, weiß aber nichts (mehr) über die Eigenheiten und Details des Projekts. Es macht wenig Sinn, Software- oder Datenanalyseprojekte so zu dokumentieren, dass selbst eine absoluter Laie sie verstehen kann. 39 | 40 | ## Projekt benennen 41 | 42 | Dinge kurz und verständlich zu benennen ist eine Herausforderung, vor allem wenn es dabei um den Namen eines neuen Github-Repositories geht. Wir benennen unsere Repositories nach folgendem Schema: 43 | 44 | ```text 45 | (jahr)-titel-typ 46 | ``` 47 | 48 | Projekte bekommen nur dann eine **Jahreszahl**, wenn sie in einem bestimmten Jahr abgeschlossen und veröffentlicht wurden. Meistens sind das Datenanalysen oder Recherchen. Anleitungen, Services und Werkzeuge bekommen keine Jahreszahl, da sie laufen weiterentwickelt werden. 49 | 50 | Der **Titel** sollte sprechend sein und das Thema möglichst kurz und genau beschreiben. Der Titel kann mehrere Wörter enthalten, diese sollten jedoch ebenfalls kleingeschrieben und durch einen Bindestrich getrennt werden. 51 | 52 | Als letztes wird der **Typ des Repositories** angegeben. Gute Suffixe sind: 53 | 54 | - **-analyse**: Datenanalyse oder -auswertung 55 | - **-longread**: Artikel mit interaktiven Elementen 56 | - **-chart**: Grafik oder Datenvisualisierung 57 | - **-website**: Webseite mit mehren Seiten 58 | - **-data**: Sammlung an (Roh-)Daten, ohne Skripte 59 | - **-service**: API oder Micro-Service 60 | - **-tool**: Werkzeug, um eine bestimmte Aufgabe zu lösen 61 | - **-guide**: Anleitung, um etwas zu tun 62 | 63 | Beispiele für gute Repository-Namen: 64 | 65 | - **2019-db-aufzuege-analyse**: Abgeschlossene Analyse der ausgefallenen Aufzüge an Bahnhöfen der Deutschen Bahn. 66 | - **waffenexporte-libyen-analyse**: Laufende Analyse von Waffenexporten nach Libyen. 67 | - **elasticsearch-import-tools**: Mehrere Werkzeuge um Daten in Elasticsearch zu importieren. 68 | 69 | ## README schreiben 70 | 71 | Eine Vorlage für ein typische README-Datei findet sich hier: [README.template.md](https://github.com/digitalegarage/open-source-guidelines/blob/master/README.template.md) 72 | 73 | Die Readme-Datei ist die zentrale Quelle für Dokumentation und Informationen über ein Projekt. Ein gut geschriebenes Readme erleichtert den Einstieg in ein Projekt und vermittelt Kompetenz und Ernsthaftigkeit. Im Idealfall umfasst das Readme: 74 | 75 | - **Projekttitel:** Um was geht es bei dem Projekt? 76 | - **Projektbeschreibung:** Welche Funktionen oder Erkenntnisse (bei Analysen) bietet das Projekt? Was macht das Projekt besonders? 77 | - **Demo- oder Artikellink:** Wie sieht das Projekt aus, wenn alles funktioniert? Wie fühlt sich die Benutzeroberfläche an? 78 | - **Datenquelle:** Woher kommen die Daten und wie kann ich sie verwenden (Copyright)? 79 | - **Abhängigkeiten:** Was brauche ich zusätzlich, um das Projekt zum Laufen zu bekommen (z.B. Python 2.7 und PostgreSQL)? 80 | - **Verwendung:** Was muss ich machen, um das Projekt zu verwenden? 81 | - **Funktionen:** Welche Funktionen (oftmals Skripten) hat das Projekt und wie verwende ich diese im Detail? 82 | - **Probleme:** Welche häufigen Probleme gibt es (und wie gehe ich damit um)? 83 | - **Verbesserungen oder Roadmap:** Was kann man besser machen? Wo steht das Projekt und wo soll es mal hin? 84 | - **Dank und Quellen:** Wer hat zum dem Projekt beigetragen, wovon wurde das Projekt inspiriert? 85 | 86 | **Wie umfangreich sollte das Readme sein?** In das Readme gehören alle Informationen, die unmittelbar notwendig sind, um das Projekt zu verwenden. Details, wie man eine bestimmte Datenbank aufsetzt, muss man nicht ausführen. Hier reicht ein Link oder zumindest der Hinweis, dass die Installation einer bestimmten Datenbank vorausgesetzt wird (Stichwort Anforderungen). 87 | 88 | **Wann sollte ich damit anfangen, ein Readme zu schreiben?** Am besten sofort. Eigentlich sollte man alle Funktionen, die man neu hinzufügt, gleich dokumentieren. Das ist deutlich einfacher als sich am Ende des Projektes nochmal über alle Funktionen Gedanken machen zu müssen. Außerdem merkt man beim Dokumentieren schnell, ob eine Funktion sinnvoll definiert ist (selbsterklärende Schnittstelle, Abstraktionsniveau). 89 | 90 | **Deutsch oder Englisch?** Grundsätzlich empfiehlt sich, alles in Englisch zu dokumentieren. Wenn ein Projekt aber ein ausschließlich deutsches Thema behandelt, kann man aber zumindest die README in Deutsch verfassen. Eine besondere Schwierigkeit ist die Übersetzung von deutschen Behördennamen oder Rechtsbegriffen. Im Fall von *Einspeisevergütung* beispielsweise bietet es sich an, den Originalbegriff und eine Übersetzung zu verwenden: *feed-in tariffs (Einspeisevergütung)*. 91 | 92 | Die Dokumentation im Code, sowie Variablen- und Funktionsnamen, sollten eigentlich immer englisch sein. Allerdings gilt auch hier die Ausnahme für Behördennamen und Rechtsbegriffen. 93 | 94 | ## Dokumentation und Kommentare 95 | 96 | Die Dokumentation im Code sollte zielführend und dem Umfang des Projekts angemessen sein. Am wichtigsten sind aber sprechende Variablen-, Funktions- und Klassennamen. Wenn eine Funktion `toDashCase(string)` heißt, muss man eigentlich nicht mehr viel kommentieren. Oft ist es wichtiger die zu erwartenden Parameter zu beschreiben. Hier sollte man gängige Konventionen wie [JSDoc](http://usejsdoc.org/) oder [pydoc](https://docs.python.org/2/library/pydoc.html) befolgen: 97 | 98 | ```javascript 99 | /** 100 | * @param {string} Word or sentence 101 | */ 102 | 103 | function toDashCase(string) { 104 | 105 | return string.replace(/\s+/g, '-').toLowerCase() 106 | } 107 | ``` 108 | 109 | Für **Datenanalysen** empfiehlt es sich [Jupyter Notebooks](https://jupyter.org/) oder [R Markdown](http://rmarkdown.rstudio.com/) zu verwenden. 110 | 111 | ## Commit-Messages 112 | 113 | Beim Veröffentlichen des Repositories wird auch der ganze Commit-Verlauf nach außen hin sichtbar. Das sollte eine Motivation sein, sich auch in Zukunft besonders viel Mühe bei den Commit-Messages zu geben. Gute Commit-Messages beginnen mit einem Verb (Imperativ Präsens, erster Buchstabe großgeschrieben) und sind nicht länger als 50 Zeichen. Außerdem braucht man am Ende der Commit-Message keinen Punkt zu setzen. 114 | 115 | Beispiel: 116 | 117 | ```console 118 | $ git commit -m "Fix social media icon alignment in header" 119 | ``` 120 | 121 | ## Große Dateien vermeiden 122 | 123 | Das Einchecken von großen Dateien, vor allem Binärdateien (.zip, .jpeg, .pdf, .mp3, ...), sollte vermieden werden, da Git dadurch sehr langsam wird. Das gilt vor allem dann, wenn man regemäßig geänderte Versionen dieser Binärdateien einchecken muss. Ein paar Bilder mit jeweils einem Megabyte sind in der Regel kein Problem, bei hunderten Bildern oder einer 500 Megabyte großen Datei wird Git jedoch schon merklich langsamer. 124 | 125 | Es empfiehlt sich daher, viele oder sehr große Binärdateien extern zu speichern, zum Beispiel bei Dropbox, Google Drive oder einem anderen Cloud-Anbieter. Eine weitere gute Lösung ist [Git LFS](https://git-lfs.github.com/) (Large File Storage), welches eine nahtlose Integration in Git ermöglicht. Git LFS verarbeitet große Dateien, indem es nur einen Verweis (*Pointer*) auf die große Datei im Repository ablegt, nicht aber die Datei selbst. Große Dateien werden auf speziellen Github-Servern gespeichert, können aber auch bei anderen Cloud-Anbietern gespeichert werden. 126 | 127 | Sehr große Repositories kann man deutlich schneller klonen, wenn man nur den letzten Änderungsstand mit `--depth=1` herunterlädt. Das beschleunigt das Arbeiten mit Git erheblich. 128 | 129 | ```console 130 | $ git clone --depth=1 git@github.com:br-data/mein-repo.git 131 | ``` 132 | 133 | ## Passwörter entfernen 134 | 135 | Manchmal hat man versehentlich Passwörter, API-Keys oder andere vertrauliche Informationen in einem Repo eingecheckt. Diese sollte man unbedingt vor Veröffentlichung des Projektes entfernen. Am einfachsten geht das mit dem [BFG Repo Cleaner](https://rtyley.github.io/bfg-repo-cleaner/). Es empfiehlt sich, das Projekt vorher zu sichern. 136 | 137 | Als erstes muss das Repository gespiegelt werden: 138 | 139 | ```console 140 | $ git clone --mirror git@github.com:br-data/mein-repo.git 141 | ``` 142 | 143 | Möglichkeit A: Alle Dateien löschen die *id_rsa* oder *id_dsa* heißen: 144 | 145 | ```console 146 | $ bfg --delete-files id_{dsa,rsa} mein-repo.git 147 | ``` 148 | 149 | Möglichkeit B: Alle Dateien nach Passwörtern aus einer Liste durchsuchen und mit `***REMOVED***` ersetzen: 150 | 151 | ```console 152 | $ bfg --replace-text passwords.txt mein-repo.git 153 | ``` 154 | 155 | Um folgende Befehle auszuführen, muss man in das Verzeichnis wechseln: 156 | 157 | ```console 158 | $ cd mein-repo.git 159 | ``` 160 | 161 | Alle Referenzen aktualisieren und alte Referenzen löschen: 162 | 163 | ```console 164 | $ git reflog expire --expire=now --all && git gc --prune=now --aggressive 165 | ``` 166 | 167 | Referenzen pushen. 168 | 169 | ```console 170 | $ git push 171 | ``` 172 | 173 | **Warnung:** Sobald Passwörter in ein öffentliches Repository eingecheckt wurde, sollte man sie als kompromittiert betrachten. In diesem Fall hilft es nur, die betroffenen Passwörter auszutauschen. API-Keys und Auth-Tokens müssen neu generiert werden. 174 | 175 | **Vorsorge:** Um zu verhindern, dass sensible Daten eingecheckt werden, sollte man vorsichtig mit globalen Kommandos wie `git add -A` umgehen. Besser ist es, Dateien einzeln zu einem Commit hinzuzufügen. Auf jeden Fall sollten vor einem Commit noch einmal die vorgeschlagenen (staged) Dateien angeschaut werden: `git status`. Um ein versehentliches Einchecken zu verhindern, kann man sensible Konfigurationsdateien auch zur `.gitignore` hinzufügen. Ein .gitignore-Beispiel findet sich in diesem Repository unter `.gitignore`. 176 | 177 | ## Badges hinzufügen 178 | 179 | Sehr beliebt sind sogenannte Badges oder Shields. Sie zeigen bestimmte Projektinformationen, wie die Lizenz, der Build-Status oder die Zahl der Issues, direkt in der README an. Ein vollständige Übersicht findet sich bei [Shields.io](https://shields.io/). Dort kann mit wenigen Klicks Badges für verschiedene Zwecke selbst erzeugen. 180 | 181 | Beispiele aus dem Projekt [elasticsearch-frontend](https://github.com/br-data/elasticsearch-frontend): 182 | 183 | [![License](https://img.shields.io/github/license/br-data/elasticsearch-frontend.svg?style=flat-square)]() [![GitHub release](https://img.shields.io/github/release/br-data/elasticsearch-frontend.svg?style=flat-square)]() [![GitHub issues](https://img.shields.io/github/issues/br-data/elasticsearch-frontend.svg?style=flat-square)]() 184 | 185 | Man sollte sich aber genau überlegen, welche Badges wirklich Sinn machen. Die meisten Informationen sieht man in Github auch so auf einen Blick und mehr als fünf Badges wirken eher unseriös (siehe Heckscheibenaufkleber). 186 | 187 | ## Lizenz hinzufügen 188 | 189 | Damit andere Benutzer den Code für ihre eigenen Projekte nutzen können, braucht das Repository eine Lizenz: 190 | 191 | 1. Auf der Github-Projektseite **Create new file** auswählen. 192 | 2. Als Name der Datei `LICENSE` eingeben. 193 | 3. Vorlage **MIT** aus der Liste rechts auswählen. 194 | 4. Copyright-Zeile in `Copyright (c) 2020 Bayerischer Rundfunk` ändern. 195 | 5. Unten auf der Seite eine Commit-Beschreibung `Add license` eingeben und bestätigen. 196 | 197 | **Warnung:** Wichtig ist, dass die Urheberrechte für alle im Repository enthaltene Inhalte (Code, Text, Daten, Schriften, Bilder ...) beim Bayerischen Rundfunk liegen. Fremdinhalte wie Software-Bibliotheken sollten immer über einen Paketmanager – wie beispielsweise [npm](https://www.npmjs.com/), [yarn](https://yarnpkg.com/) oder [pip](https://pypi.python.org/) – installiert werden. 198 | 199 | Eine Beispiel-Lizenz (MIT) findet sich in diesem Repository unter `LICENSE`. 200 | 201 | ## Einstellungen anpassen 202 | 203 | Für viele kleinere Projekte ist nicht davon auszugehen, dass sich darum einen Community bilden wird. Die Veröffentlichung dient dabei eher der Transparenz als der Nutzbarmachung. Daher kann man sich überlegen, ob man folgende Optionen in den Projekteinstellungen (Github-Settings > Options) auszuschalten: 204 | 205 | - **Wikis**: Eher für die ausführliche Projektdokumentation gedacht. 206 | - **Issues**: Benutzer und Kollegen können Fehler melden und sich Funktionen wünschen. 207 | - **Projects**: Kanban-Board, Todos und Milestones für größere Projekte. 208 | 209 | Wenn man diese Optionen aktiviert, sollte man auch bereit sein, Zeit in die Bearbeitung von Benutzerwünschen und Bugs zu investieren. 210 | 211 | ## Projekt veröffentlichen 212 | 213 | Das Veröffentlichen geschieht über die Github-Settings > Options: 214 | 215 | 1. Projekt veröffentlichen: **Make this repository public** 216 | 2. Eigentumsrechte auf `br-data` übertragen: **Transfer ownership** 217 | 218 | Das Übertragen der Eigentumsrechte kann einige Minuten dauern. 219 | 220 | ## Lokales Projekt anpassen 221 | 222 | Wenn man das Repository bereits aus dem eigenen Rechner ausgecheckt hat, muss man den Remote-URL anpassen. Vergisst man die die Remote-URL anzupassen kann man nicht mehr Pushen und Pullen. Die neue URL bekommt man, indem man auf der Github-Projektseite auf **Clone or download** geht. Es empfiehlt sich immer den SSH-Link zu kopieren (statt des HTTPS-Links). 223 | 224 | #### Github Desktop 225 | 226 | 1. In der rechten oberen Ecke auf *Settings (⚙️) > Repository Settings...* gehen 227 | 2. In der Sidebar *Remote* auswählen 228 | 3. Im Feld *Primary remote repository* die URL austauschen 229 | 4. Mit *Ok* bestätigen und versuchsweise synchronisieren 230 | 231 | #### Kommandozeile 232 | 233 | Die Remote-URL kann man auch mit folgendem Kommandozeilenbefehl ändern: 234 | 235 | ```console 236 | $ git remote set-url origin git@github.com:br-data/mein-repo.git 237 | ``` 238 | 239 | Um zu überprüfen, ob die Änderung geklappt hat, kann man sich die Remote-URL mit folgendem Befehl anschauen: 240 | 241 | ```console 242 | $ git remote -v 243 | origin git@github.com:br-data/mein-repo.git (fetch) 244 | origin git@github.com:br-data/mein-repo.git (push) 245 | ``` 246 | 247 | ## Gute Beispiele 248 | 249 | Gute Beispiele, wie man als Nachrichtenorganisation Daten und Analysen veröffentlichen kann, finden sich bei: 250 | 251 | - [SRF Data auf Github](https://github.com/srfdata/) 252 | - [Correctiv! auf Github](https://github.com/correctiv/) 253 | 254 | ## Kontakt 255 | 256 | [BR Data](http://br.de/data/) ist das datenjournalistische Team des [Bayerischen Rundfunks](http://br.de/). Es setzt sich zusammen aus Journalisten, Entwickler und Designern. Wir haben uns auf daten- und dokumentengetriebene Recherche und ihre Umsetzung in interaktiven Anwendungen und im crossmedialen Umfeld spezialisiert. 257 | 258 | Wir freuen uns über Fragen, Kritik oder Anregungen: 259 | 260 | - BR Data auf Twitter [@br_data](https://twitter.com/br_data/) 261 | - BR Data per [E-Mail](mailto:data@br.de) kontaktieren 262 | -------------------------------------------------------------------------------- /README.template.md: -------------------------------------------------------------------------------- 1 | # README-Vorlage 2 | 3 | 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. 4 | 5 | - **Demo:** [Original README-Vorlage bei Github](https://github.com/digitalegarage/open-source-guidelines/blob/master/README-template.md) 6 | 7 | ## Datenquelle 8 | 9 | Dieses README baut auf den Ideen von Stephen Whitmore's [Art of README](https://github.com/noffle/art-of-readme) auf. 10 | 11 | ## Abhängigkeiten 12 | 13 | Dieses Readme ist in [Markdown](https://guides.github.com/features/mastering-markdown/) geschrieben. Um es zu bearbeiten reicht ein einfacher Text-Editor wie [Sublime Text](https://www.sublimetext.com/). Um eine HTML-Vorschau zu erzeugen benötigt es allerdings ein Plugin wie [sublimetext-markdown-preview](https://github.com/revolunet/sublimetext-markdown-preview). Eine Liste anderen Markdown-Editoren gibt es [hier](https://github.com/karthik/markdown_science/wiki/Tools-to-support-your-markdown-authoring). 14 | 15 | ## Verwendung 16 | 17 | 1. Repository klonen `git clone https://...` 18 | 2. README bearbeiten `subl README.md` 19 | 3. Änderungen einchecken `git add README.md` und committen `git commit -m "Update README"` 20 | 21 | ## Funktionen 22 | 23 | Tipps, um semantische READMEs mit Markdown zu schreiben. Ein vollständige Dokumentation der Funktionen bietet das [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). 24 | 25 | ### Textformatierung 26 | 27 | Hervorhebungen lassen sich in Markdown folgendermaßen gestalten: 28 | 29 | - **Text fett**: `**fett**` 30 | - *Text kursiv*: `*fett*` 31 | 32 | Außerdem gibt es verschiedene Überschriften: 33 | 34 | # H1 35 | ## H2 36 | ### H3 37 | #### H4 38 | ##### H5 39 | ###### H6 40 | 41 | Die Überschriften unterscheiden sich jeweils durch die Anzahl der vorangestellten Rauten `## H2`. 42 | 43 | ### Aufzählungen 44 | 45 | Markdown bietet die Möglichkeit verschiedene Aufzählungen anzulegen. 46 | 47 | Unsortierte Aufzählungen mit vorangestellten Bindestrichen `-`: 48 | 49 | - Listeneintrag 50 | - anderer Listeneintrag 51 | - noch ein Listeneintrag 52 | 53 | Sortierte Aufzählung mit vorangestellten Zahlen `1.`: 54 | 55 | 1. Erster Listeneintrag 56 | 2. Zweiter Listeneintrag 57 | 3. Dritter Listeneintrag 58 | 59 | ### Links und Bilder 60 | 61 | Links bestehen jeweils aus einem Linktext und einer URL `[Linktext](http://github.com/br-data)`. 62 | 63 | Beispiel: [Zur README-Vorlage](https://github.com/digitalegarage/open-source-guidelines/blob/master/README-template.md) 64 | 65 | Bilder können nach dem gleichen Prinzip eingebunden werden. Einziger Unterschied ist das führende Ausrufezeichen `![Bildbeschreibung](https://de.wikipedia.org/wiki/Datei:GitHub_logo_2013.svg)` 66 | 67 | ![Github-Logo](https://de.wikipedia.org/wiki/Datei:GitHub_logo_2013.svg) 68 | 69 | ### Code 70 | 71 | 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`. 72 | 73 | Beispiel: 74 | 75 | ```javascript 76 | function add(a, b) { 77 | return a+b 78 | } 79 | 80 | add(1, 2) // returns 3 81 | ``` 82 | 83 | ## Probleme 84 | 85 | Manchmal funktioniert der Markdown-Renderer nicht. In diesem Fall hilft meistens ein Neustart des Text-Editors. 86 | 87 | ## Verbesserungen 88 | 89 | - Beispiel-Readme auf Englisch hinzufügen 90 | - Einstellungen im Text-Editor ausführlicher beschreiben 91 | 92 | ## Dank und Quellen 93 | 94 | - Philosophie: [Art of README](https://github.com/noffle/art-of-readme) 95 | - Markdown-Beispiele von [Github Markdown](https://guides.github.com/features/mastering-markdown/) und [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) 96 | --------------------------------------------------------------------------------