© GreenFlash/Shutterstock.com
Kolumne: Hitchhiker’s Guide to Docs as Code

Kolumne: Hitchhiker’s Guide to Docs as Code


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 [1]. 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 [3]: 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 [4]: 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 https://arc42.org über diesen Dienst.

  • Eine Übersicht weiterer Sitegeneratoren finden Sie unter [5], wir erwähnen hier einmal Hugo und JBake als relativ prominente Vertreter.

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 Conte...

Neugierig geworden?

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang