GitHub Pages: Einfache Dokumentation von Projekten
Ich hatte schon sehr lange vor, mich mit dem Thema GitHub Pages auseinander zu setzen – bisher habe ich es aber immer vor mir her geschoben. Wer hat schon Lust Doku zu schreiben?
Einleitung
Eigentlich ist GitHub Pages ein Dienst, welcher einfach nur statisches HTML annimmt und ausgibt. Keine Datenbanken, kein PHP, keine Dynamik. Also braucht man etwas anderes. Entweder man aktualisiert nun ständig seinen Content per Hand und Pusht ihn dahin, oder man lässt alles mit Jekyll generieren (denn das kann GitHub Pages!). So bekommt man dann doch etwas Dynamik zurück. Wie genau das geht, möchte ich in diesem Beitrag beleuchten.
Das schöne ist, dass alles eng mit GitHub verknüpft ist – die Dokumentation ist also immer auf dem gleichen Stand wie das Repo. Und zwar sofort – ohne irgendwelchen verrückten Hooks oder Deployment-Scripts. Nebenbei muss man sich nichtmal um das Hosting kümmern. Das macht es wirklich sehr angenehm!
In diesem Beitrag möchte ich beschreiben, wie ich mit GitHub Pages eine Dokumentation für EasyTemplate erstelle und veröffentliche. Das Ganze wird mit Jekyll generiert.
Erste Schritte
Also ich habe jetzt schon ein Repo und möchte das Ganze dokumentieren. Möglichst einfach natürlich. Dazu erstellen wir zunächst einmal einen neuen Branch namens gh-pages (dieser Name muss genauso geschrieben werden).
|
1 |
git checkout --orphan gh-pages |
Bei dieser Gelegenheit habe ich auch direkt eine neue Option kennengelernt: „orphan“. Orphan ist Englisch und bedeutet Waise. Heißt: Dieser Branch hat keine Eltern (Parents), und der erste commit hängt somit einfach irgendwo in der Gegend herum ohne Beziehung zu einem anderen Branch. Schon cool – ich habe mir eben schon überlegt, wie ich diesen Branch wohl anlegen kann, ohne einen zu erstellen, in dem mein erster Commit „Alles löschen!“ heißt. Frage beantwortet.
Aber genug git-Tutorial. Weiter im Text. Blöderweise sind im neuen Branch dann noch alle Dateien da, aber nicht mehr im Repo. Also erstmal alles löschen was da so rumschwirrt (keine Sorge, bleibt alles im anderen Branch und natürlich auch im Repo enthalten):
|
1 2 |
git rm -r --cached * rm -rf * |
(Bitte nur im Repo-Verzeichnis selbst ausführen – sonst könnte sehr viel gelöscht werden. Dreimal kontrollieren! Ihr wisst ja, wofür Sternchen steht)
git status sollte nun folgendes ausgeben:
|
1 2 3 4 5 |
On branch gh-pages Initial commit nothing to commit (create/copy files and use "git add" to track) |
Jetzt könnten wir natürlich anfangen und langweiliges HTML-Zeug erstellen. Den Schritt überspringen wir aber direkt. Das setze ich mal als Wissen voraus und HTML-Grundkenntnisse kann man auf anderen Seiten im Netz viel besser erlangen, als ich das hier kurz beschreiben könnte.
Da Jekyll in Ruby geschrieben ist, können wir es einfach per gem installieren. Aktuell ist gerade Version 2.5.3. Jekyll brauchen wir wirklich nur für die lokale Entwicklungsumgebung (damit wir nicht ständig alles pushen müssen). GitHub Pages versteht das nachher ebenfalls.
|
1 |
gem install jekyll |
(auf dem Mac muss ich gem komischerweise immer mit sudo aufrufen – ansonsten bekomme ich Fehlermeldungen, dass ich keine Rechte habe)
Da ich mich immernoch im Verzeichnis meines Repos (dank neuem Branch in einem leeren Verzeichnis) befinde, kann ich einfach eine neue Seite mit dem folgenden Kommando erstellen:
|
1 |
jekyll new . |
(Punkt ist hierbei das aktuelle Verzeichnis – UNIX Basics und so – geht natürlich von überall, wenn man den Pfad entsprechend anpasst)
Damit der Befehl funktioniert muss das Zielverzeichnis leer sein! Ansonsten beschwert sich Jekyll sehr schnell. Aber wir haben ja oben alles gelöscht – also keine Fehlermeldung bekommen. Sehr gut!
Danach findet man allerhand Dateien im Verzeichnis:
|
1 2 3 4 5 6 7 8 9 10 |
-rw-r--r-- 1 matthiaskleine admin 18 Jul 23 19:02 .gitignore -rw-r--r-- 1 matthiaskleine admin 557 Jul 23 19:02 _config.yml drwxr-xr-x 2 matthiaskleine admin 170 Jul 23 19:02 _includes drwxr-xr-x 2 matthiaskleine admin 170 Jul 23 19:02 _layouts drwxr-xr-x 2 matthiaskleine admin 102 Jul 23 19:02 _posts drwxr-xr-x 2 matthiaskleine admin 170 Jul 23 19:02 _sass -rw-r--r-- 1 matthiaskleine admin 470 Jul 23 19:02 about.md drwxr-xr-x 2 matthiaskleine admin 102 Jul 23 19:02 css -rw-r--r-- 1 matthiaskleine admin 1291 Jul 23 19:02 feed.xml -rw-r--r-- 1 matthiaskleine admin 506 Jul 23 19:02 index.html |
Schon mal toll. Ich bin ja neugierig und rufe die index.html mal direkt im Browser auf.
Mh. Das sieht ja noch nicht so spektakulär aus, oder? Liegt daran, dass es so nicht funktioniert. Die vielen Prozentzeichen lassen schon vermuten, dass es sich dabei um Platzhalter und Anweisungen handelt. Sieht etwas aus wie Twig finde ich.
Aber rufen wir mal folgendes auf:
|
1 |
jekyll serve --watch |
Wenn wir jetzt http://127.0.0.1:4000/ im Browser öffnen (die URL teilt uns Jekyll nach dem Aufruf auch mit), bekommen wir schon etwas schöneren Inhalt geliefert.
Sehr cool! Das sieht doch schon mehr nach einer Website aus, oder? Die Option –watch bedeutet, dass Jekyll nun automatisch die Seite immer wieder neu baut, sobald wir Änderungen an einer der Dateien durchführen. So kann man das Bauen etwas einfacher gestalten.
In der _config.yml im aktuellen Verzeichnis finden wir ein wenig Konfiguration (wer hätte das gedacht), welche wir anpassen können/müssen/sollten. Standardmäßig ist zum Beispiel der Markdown-Parser kramdown aktiv. Da redcarpet aber angeblich cooler ist (und auch viel mehr Stars auf GitHub hat), nutzen wir lieber diesen Parser.
Meine _config.yml habe ich wie folgt bearbeitet:
|
1 2 3 4 5 6 7 8 |
# Site settings title: Webguys EasyTemplate email: matthias@webguys.de baseurl: /EasyTemplate # Build settings markdown: redcarpet highlighter: pygments |
(die _config.yml ist vom Watch-Flag als einzige sehr unbeeindruckt – um die Änderungen zu sehen, bitte Jekyll neustarten)
Wer sich nun fragt: Was ist Pygments? Gute Frage! Das ist ein Syntax-Highlighter. Macht ja schon irgendwie Sinn, wenn man Code dokumentieren möchte, oder? Ansonsten sollte die baseurl identisch mit dem Namen des Repos sein, damit die Pfade später auch stimmen.
Doch ein anderes Theme
Jetzt könnte man anfangen, und sein eigenes Jekyll-Template aufbauen. Ist aber nicht so supergeil und wir sind ja keine Designer. Außerdem möchte ich ja schnell zu einem Ergebnis kommen. Wenn man nach Themes für GitHub Pages sucht, findet man relativ schnell das Theme Minimal von orderedlist. Sieht auch schön aus, ist allerdings ist es nur HTML und von Jekyll ist weit und breit nichts zu sehen. Außerdem möchten wir doch in Markdown schreiben und nicht in HTML.
Abhilfe schafft dieses Repo von GochoMugo. Hier hat sich jemand schon einmal die Arbeit gemacht, und das Minimal-Theme in Jekyll gepackt.
Also wisst ihr was? Prinzip verstanden, oder? Wir schmeißen noch einmal weg und fangen auf der Basis von GochoMungo neu an.
Da wir uns ja schon in einem Repo befinden, können wir hier nicht noch ein neues klonen. Also einfach das Zip laden.
|
1 2 3 4 5 6 |
wget https://github.com/GochoMugo/minimal-jekyll/archive/gh-pages.zip unzip gh-pages.zip rm gh-pages.zip mv minimal-jekyll-gh-pages/* . mv minimal-jekyll-gh-pages/.gitignore . rm -rf minimal-jekyll-gh-pages/ |
Dann noch einmal die _config.yml angepasst:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
title: Webguys EasyTemplate project_name: EasyTemplate description: > A simple page builder for magento repository_url: https://github.com/webguys-de/EasyTemplate repository_shorthand: webguys-de/EasyTemplate baseurl: "/EasyTemplate" author_name: Webguys author_url: http://www.webguys.de/ markdown: redcarpet highlighter: pygments |
Danach können wir das Ergebnis schon begutachten mit einem:
|
1 |
jekyll serve --watch |
Sieht dann so aus:
Meiner Meinung nach schon sehr geil! Was will man mehr?
Etwas blöd: Die index.html ist nach wie vor html… Diese löschen wir mal als erstes. Statt dessen legen wir eine index.md im docs-Verzeichnis an. Mit folgendem Inhalt:
|
1 2 3 4 5 6 7 8 |
--- layout: default permalink: / --- # Home Welcome home! |
Das wars auch schon. Allein durch den Permalink haben wir schon gewonnen. Immer wenn die Base-Url aufgerufen wird, wird nun also diese Datei geladen. Einfach, oder?
Dann habe ich noch die styles des syntax-highlighting ausgetauscht, damit das Ganze etwas cooler aussieht und lesbar ist.
Dann kann das schreiben ja losgehen! Einfach alle Dateien in den docs Ordner legen, entsprechende Permalinks reinpacken und diese in der menu.yml eintragen. Das sollte es dann auch schon gewesen sein!
Die Dokumentation publizieren
Einfach per git add, commit und push:
|
1 2 3 |
git add . git commit -m "Documentation INIT" -a git push -u origin gh-pages |
Und da sind wir auch schon: webguys-de.github.io/EasyTemplate/
Die URLs sind immer wie folgt aufgebaut: <username>.github.io/<repository>
Links
Wer weitere Themes für Jekyll sucht, wird hier bedient:
- Themes: github.com/jekyll/jekyll/wiki/Themes
- Noch mehr Themes: drjekyllthemes.github.io
- Beispiele für coole Seiten (nicht nur Dokumentationen) mit Jekyll gibt es hier
Themes, welche mir gut gefallen
Über Matthias Kleine
Jahrgang 87, gelernter Softwareentwickler und 15 Jahr Erfahrung im Bereich Web-Entwicklung mit PHP. Weiterhin bin ich seit Ende 2013 Magento Certified Developer.
