Kolumne

Hitchhiker’s Guide to Docs as Code: Websites mit AsciiDoctor & Jekyll

Gernot Starke, Ralf D. Müller

©S&S Media

Wir zeigen Ihnen in dieser Folge, wie Sie statische Websites mithilfe von AsciiDoc erstellen und pflegen können. Dazu greifen wir etwas tiefer in die Werkzeugkiste der Softwareentwicklung, nämlich zum Ruby-basierten Generator Jekyll. Jekyll selbst verwendet standardmäßig Markdown als Auszeichnungssprache, für AsciiDoc müssen wir ein klein wenig nachhelfen. Alternative Ansätze diskutieren wir im Textkasten „Alternativen zu Jekyll“.

Bislang haben wir Ihnen in dieser Kolumne gezeigt, wie Sie mit AsciiDoc Ihre arc42-Architekturdokumentation generieren können. Das Ergebnis waren bisher hauptsächlich Dokumente (als PDF oder auch HTML). Oft benötigen Sie aber auch eine richtige Website mit ordentlicher Landingpage oder einem zusätzlichen Blog für Ihr Projekt. Mit einem Static-Sitegenerator erledigen Sie diese Aufgabe mithilfe der gleichen Ansätze. Im Gegensatz zur bislang dargestellten linearen Dokumentation weist eine richtige Site meist eine komplexere Navigation auf. Das kann beispielsweise eine Auflistung aller Blogposts zu einem bestimmten Thema (Tag oder Label) sein. Genau dabei nimmt uns Jekyll als Generator die Arbeit ab: Wir können Navigationsstrukturen deklarieren und unseren gesamten Content in Markdown oder AsciiDoc schreiben. Der freundliche Generator baut daraus eine schicke Website zusammen.

Alternativen zu Jekyll

Wie fast immer in der IT, gibt es auch bei der Generierung von Websites aus AsciiDoc einige Alternativen:

  • Völlig rudimentär: Sie verwenden den vom AsciiDoc-Prozessor generierten HTML-Output direkt, entweder über GitHub Pages oder via FTP zum Webhoster Ihrer Wahl.
  • Völlig AsciiDoc: Das Antora-Projekt: Maßgeblich von Dan Allen (Lead Developer von Asciidoctor) entwickelt, ein Multi-Repository-fähiger Generator, der fundamental auf AsciiDoc basiert.
  • Völlig CI: Der Netlify-Service  – was Ihnen an GitHub Pages (vielleicht) noch gefehlt hat, unter anderem HTTPS für individuelle Domains. Ganz hervorragend integriert mit GitHub, GitLab und Bitbucket. Ermöglicht die Integration leistungsfähiger Formulare, sogar AWS-Lambda-Funktionen sind möglich. Seit März 2018 läuft beispielsweise http://arc42.org über diesen Dienst.
  • Eine Übersicht weiterer Sitegeneratoren finden Sie hier, wir erwähnen hier einmal Hugo und JBake als relativ prominente Vertreter.

Da Jekyll auf Ruby basiert und eine ganze Menge weiterer Abhängigkeiten mit sich schleppt, empfehlen wir Ihnen, die ersten Schritte auf Basis eines passenden Docker-Containers zu gehen. Mit einem passenden Docker-File sowie etwas Scripting-Unterstützung haben wir die Einstiegshürde für Sie ziemlich niedrig gehalten. Wir gehen allerdings davon aus, dass Sie eine lauffähige Docker-Installation (mit Docker und Docker Compose) zur Verfügung haben. Sollten Sie Ihre Dokumentation oder Site als GitHub-Pages bereitstellen wollen: Auch GitHub verwendet Jekyll als Generator für die GitHub-Pages, allerdings können Sie dafür (Stand Mai 2018) nur Markdown verwenden. Indirekt klappt es dann aber doch – das sehen Sie in unserem Beispiel.

Grundsätzlich sieht unser Plan so aus:

1. Jekyll und die notwendigen Ergänzungen (AsciiDoc) in einen Docker-Container packen,
2. sonstige Eigenschaften der Site konfigurieren,
3. Struktur (= Navigation) der Site konfigurieren,
4. Content der Site schreiben,
5. jekyll-docker im Server Mode starten; damit können Sie Ihre Site auf localhost (respektive unter dem URL http://0.0.0.0:4000) lokal im Browser testen.

Jekyll ist ein Generator für (primär statische) Websites, in Ruby programmiert. Seine über 33 000 GitHub-Sterne sprechen ihre eigene Sprache. Dabei versucht Jekyll, Ihnen als Content-Autor möglichst aus dem Weg zu gehen. Ursprünglich hat Tom Preston-Werner, einer der Gründer von GitHub, dieses feine Stückchen Software geschrieben. Seit Februar 2018 hat Olivia Hugger die Rolle der Lead-Entwicklerin übernommen.

Themes

Jekyll verwendet zum Styling von Websites Themes, die Sie als Autoren unabhängig vom eigentlichen Kern des Generators erstellen oder auswählen können. Wir haben für diese Folge das flexible und leistungsfähige Theme Minimal Mistakes ausgewählt, das beispielsweise die Grundlage für http://arc42.org und http://aim42.org bildet.

Themes bieten in der Regel eine Auswahl sogenannter Layouts für Sites an, teilweise auch noch zusätzliche Helferlein – entweder in Form von CSS oder JavaScript. Unser vorgeschlagenes Theme Minimal Mistakes beispielsweise kennt ein schickes Splash-Layout, kann Grafiken als Seitenheader einbinden und mit Überschriften überlagern, kann Inhaltsverzeichnisse erstellen, hat eine (einfache) Suchfunktion und eine Menge weiterer nützlicher Features. Wir haben das Theme als Remote Theme konfiguriert, das heißt, wir brauchen keine Theme-spezifischen Files in unserem Repository zu halten, sondern lassen sie zur Build Time laden.

Plug-ins

Sie können Jekyll durch Plug-ins um diverse Funktionen erweitern, unter anderem für AsciiDoctor (normalerweise verwendet Jekyll ja Markdown). Weitere Bereiche, in denen Plug-ins die Möglichkeiten von Jekyll erweitern können, sind Suchfunktionen, i18n, Tagging, Paginierung und viele andere.

Jekyll mit Docker

Abbildung 1 zeigt im Überblick, was wir Ihnen diesmal anbieten: Ihre Dokumentation steht in den Contentpages (im Bild unten), und in der prod-Phase generiert Jekyll daraus die Production Site (im Bild rechts). Aber fangen wir vorne an:

Wir stellen Ihnen ein Skript (_manage-site.sh, Abb. 2) bereit, mit dessen Hilfe Sie die wesentlichen Operationen (build, develop, production, upload) starten können (Textkasten: „‚develop‘ und ‚production‘“). Im Wesentlichen kapselt dieses Skript die länglichen Kommandos zur Nutzung von Docker und Jekyll. In unserem Repository verstecken wir dieses Skript hinter Gradle. Das läuft dann (im Gegensatz zum Skript) auch unter Windows, und Sie können es einfach in Ihren gesamten Gradle Build integrieren.

Starten Sie _manage-site.sh und wählen die Option BUILD. Damit starten Sie die Erzeugung (build) des notwendigen Docker Image (hhgdac/jekyll). Das Image basiert auf dem Builder Image von Jekyll und fügt in einem zusätzlichen Layer noch das gewählte Jekyll Theme und weitere Kleinigkeiten hinzu. Die notwendigen Installationsanweisungen für Jekyll stehen in der Datei Gemfile.

Nun können Sie damit loslegen, Ihre Website zu entwickeln (develop). Konfigurieren Sie relevante Sitedetails (Namen, Kontaktinfos etc) in der Datei _config.yml. Dann starten Sie mit Hilfe unseres _manage-site.sh-Skripts Jekyll im develop-Modus: Jekyll übersetzt dann Ihre Contentpages ins Verzeichnis /_site und startet einen internen Webserver, den Sie auf der Adresse http://0.0.0.0:4000 erreichen können. Änderungen in Ihren Contentpages übersetzt Jekyll inkrementell neu. Falls Sie an der Konfiguration etwas ändern, müssen Sie den develop-Server neu starten (unterbrechen Sie dazu das laufende Container-Image mit CTRL + C).

Wenn Sie Ihren Content auf einem produktiven Server veröffentlichen möchten, nutzen Sie das production-Kommando des _manage-site.sh-Skripts: Das bewegt Jekyll dazu, Ihre Site mit dem richtigen Ziel-URL neu zu generieren und das Ergebnis als rein statische Site im Verzeichnis /zz-prod-dir abzulegen. Den Inhalt dieses Verzeichnisses kopieren Sie 1:1 auf Ihren Webserver – weitere Magie ist nicht erforderlich.

Abb. 1: Übersicht Jekyll mit Docker

Abb. 2: Skript zum Starten der wesentlichen Aktionen

„develop“ und „production“

Für die Aufgaben develop und production verwenden wir im Hintergrund Docker Compose statt direkte Aufrufe von docker run. Im develop-Modus starten wir im Container einen Jekyll-Server, der bis zur expliziten Unterbrechung durch Sie weiterläuft. Unser einfaches _manage-site-Skript betreibt dabei keine weiteren Aufräumarbeiten, das heißt, in manchen Fällen bleiben Container im Hintergrund am Leben.

Falls Sie beim erneuten Start des <develop-Modus von seltsamen Docker-Fehlermeldungen gequält werden, könnten solche verwaisten Container die Ursache sein. In diesen Fällen hat uns ein explizites Beenden mit folgendem Kommando geholfen: docker-compose –file docker-compose-dev.yml down. Die aktuelle Version unseres _manage-site-Skripts enthält dazu ein eigenes Kommando (remove).

Der Weg zum Server

Sie können die generierte Site jetzt per FTP auf den Server Ihrer Wahl hochladen oder das auch vom Docker-Container erledigen lassen: Das upload-Kommando verwendet dazu einen zweiten Docker-Container (gernotstarke/ftp-uploader:0.2), der wiederum NcFTP benutzt. Wir hätten auch alles in einem einzigen Container erledigen können, was aber die Docker-Philosophie „one Process per Container“ verletzt hätte.

Schlusswort

Diese Folge rundet den Docs-as-Code-Ansatz ab: Sie spendieren Ihrer Dokumentation ganz einfach eine statische Website, die Sie mit denselben Tools pflegen wie Ihre restliche Dokumentation.

Wir haben damit erst einmal alles geschrieben, was wir Ihnen für moderne und codenahe Dokumentation mitgeben wollten. Wir hoffen, Ihnen hat diese Kolumne gefallen und wünschen Ihnen noch weiterhin viel Spaß und Erfolg mit Docs as Code – may the force of documentation be with you …

Geschrieben von
Gernot Starke
Gernot Starke
    Informatikstudium an der RWTH Aachen, Dissertation über Software-Engineering an der J. Kepler Universität Linz. Langjährige Tätigkeit bei mehreren Software- und Beratungsunternehmen als Softwareentwickler, -architekt und technischer Projektleiter. 1996 Mitgründer und technischer Direktor des „Object Reality Center“, einer Kooperation mit Sun Microsystems. Dort Entwickler und technischer Leiter des ersten offizielle Java-Projekts von Sun in Deutschland. Seit 2011 Fellow der innoQ GmbH.  
Ralf D. Müller
Ralf D. Müller
Ralf D. Müller arbeitet als Architekt und Entwickler. Er erlebt täglich die Notwendigkeit effektiver Dokumentation. Außerdem ist er erklärter AsciiDoc-Fan und Committer bei arc42 sowie Gründer des docToolchain-Projekts.
Kommentare

Hinterlasse einen Kommentar

Hinterlasse den ersten Kommentar!

avatar
400
  Subscribe  
Benachrichtige mich zu: