Ich bin in den letzten Wochen zum Hugo-Fan geworden. Nicht dem Drink, sondern dem CMS, beziehungsweise der “Static Website Engine”. Hugo hat ein sehr interessantes Content-Object-Modell und hat mich direkt gefesselt. Einfache Installation ohne Abhängigkeiten und einfaches Deployment.
Nachdem ich den Relaunch meiner Website chrisjung.de fast fertig (und schon einige Fallstricke umschifft) hatte, habe ich in der Firma angefangen 2 Projekte auf Hugo umzustellen.
Da wäre einerseits die Erstellung von HTML-Emails für einen Kunden, bei dem mittlerweile stolze 44 Emails aufgelaufen sind, die (notgedrungen) alle einzeln zu pflegen waren. Das hat sich durch die Umstellung auf Hugo deutlich vereinfacht. Allerdings: Hugo schmeisst HTML-Kommentare aus dem generierten HTML. Auch da gibts eine kleine Abhilfe. Und: Hugo verändert Sonderzeichen in Links. In meinem Fall war ein Link ein Platzhalter #{Placeholder}
, dessen Klammern am Ende durch die entsprechenden HTML-Entities ersetzt wurde. Eigentlich völlig richtig (und passiert auch nur bei Links im href), in diesem Fall aber unpraktisch. Außerdem müssen Sonderzeichen in den E-Mails ersetzt werden. Das ganze lässt sich mit 2 Shell-Skripten dann lösen:
- Ersetzen aller nötigen Sonderzeichen in den .md-Dateien, danach
- das Rückübersetzen der Klammern in den generierten Dokumenten.
Alle diese Schritte lassen Sich unter Linux (mein Basis-System), als auch unter Windows bewältigen (auch wenn die Aktionen der Bash-Scripte dann vermutlich per Hand ausgeführt werden müssen). Das ganze ist aus meiner Sicht für ein Team mit heterogener Entwickler-Systemumgebung dringend von nöten: Tools die wenige (am besten keine) Abhängigkeiten haben und auf allen benutzten Plattformen funktionieren. Und das macht Hugo wirklich gut.
***
Danach folgte dann als Mini-POC noch die Erstellung für API-Testformulare. Dazu wird in der zentralen Config für jede Section eine Basis-URL konfiguriert. Innerhalb der Sections werden dann pro API-Funktion Dokumente erstellt. Die Single-Pages brauchen wir nicht, die List-Templates erzeugen einfach pro Dokument ein Formular mit entsprechenden Ziel-URLs und Feldern. Die Felder werden über ein YAML-Frontmatter erstellt:
---
Output: >
{
// sample object
}
fields:
- name: sid
required: required
desc: eine Beschreibung des Feldes
value: Vorbefüllung
- name: username
required: required #optional
desc: eine Beschreibung des Feldes
value: Vorbefüllung
---
Für jeden Eintrag in der Liste “Fields” wird damit innerhalb des Formulars ein Feld erzeugt, ggf. mit Beschreibung versehen und als Pflichtfeld markiert. Damit ist die Dokumentation und die Erstellung der Testformulare quasi eins.
Für die Erstellung einer neuen Ziel-Umgebung der gleichen API muss die Section lediglich kopiert und ein neuer Pfad in der zentralen Konfiguration definiert werden. Ggf. müssen bei Funktionen wie Login noch die Default-Werte in den einzelnen Funktionen geändert werden. TOC über die Umgebungen und die Liste der Funktionen kann Hugo dann mit ein paar wenigen Zeilen einfach anzeigen.
Struktuierte API-Dokumentation und Erstellung von Testformularen: YAY!