Um die Dokumentation zu schreiben benutzen wir den Emacs Org-Mode. Die Dateien werden unter doc/content angelegt. Wir benutzen Hugo um aus den org files eine statische Website zu erzeugen. Das macht man zunächst lokal und kann seine Änderungen mit einem Webbrowser verfolgen. Möchte man, daß die Änderungen auch auf dem Webserver wirksam werden, dann werden die Änderungen des Repositories auf github publiziert (push). Über einen sogenannten webhook wird der Webserver benachrichtigt welcher sich daraufhin die Änderungen des Repositories holt, Hugo aufruft um die Website neu zu übersetzen. Dannach sind die Änderungen im www Netz verfügbar.

Repository

Klonen des Repositories

Dieser Schritt muss nur beim allerersten mal erfolgen! Mit https:

git clone https://github.com/nodecum/nodecum-learning.git

bzw wenn man dann auch Änderungen weitergeben will mit ssh:

git clone git@github.com:nodecum/nodecum-learning.git

Zusätzlich müssen noch die Submodule geholt werden:

cd nodecum-learning
git submodule update --init --recursive

Update des Repositories

Bevor man Änderungen macht ist es ratsam sich den aktuellen Stand zu holen.

cd nodecum-learning
git pull

Org-Mode

Der Org-Mode ist ein für den Menschen einfach zu lesendes Text Format welches entwickelt wurde um mit den Möglichkeiten einfacher Text Dateien sehr effizient auch komplexe Strukturen abbilden zu können. Es wurde für den Emacs Editor entwickelt und erlaubt zB das schnelle Navigieren, Auffalten und Einklappen von Strukturen, Datenbankähnliche Strukturierungen, Tabellierungen mittels einfacher Text Dateien. Das ist eine großer Vorteil gegenüber dedizierten Formaten, da man dadurch beliebige Versionierungs Software verwenden kann. Zum schreiben benutzen wir also den Org-Mode des Emacs. Man kann damit natürlich auch lesen und zb Suchen (grep).

Wir schreiben die Dokumentation aber in einer Form das damit dann eine Web Browser lesbare Form (also HTML Dateien) erzeugt wird. Dafür benutzen wir go-org welches ein Teil von Hugo, dem Webseiten Generator ist. Unter go-org doc findet man die unterstützten Org Merkmale.

Hinweise

• https://strm.sh/posts/org-mode-blogging/
• https://willschenk.com/articles/2019/using_org_mode_in_hugo/

Hugo

Hugo ist ein statischer Webseiten Generator. Das bedeutet die Quelldateien (in unserem Fall im .org Format) werden in HTML Dateien umgewandelt, welche dann die Webseiten darstellen.

Installation

snap install hugo --channel=extended

Compilieren

Um einen lokalen Webserver zu erhalten welcher die zuletzt geänderte Seite automatisch neu übersetzt:

cd nodecum-learning/doc
hugo server --navigateToChanged

danach kann man seinen Webbrowser auf die Adresse http://localhost:1313 richten um die Webseite zu betrachten. Jedes Abspeichern einer .org Datei im Verzeichnis content/ wird eine Neuübersetzung der entsprechenden HTML Datei veranlassen.