bUwUma - Build System für Webseiten

Build Websites using Make

bUwUma ist ein Build-System, welches GNU make und einen Präprozessor verwendet, um statische, mehrsprachige Websites zu erstellen.

bUwUma liefert folgende Funktionen:

• Markdown in die HTML Dateien einbinden
• Nutzung von Variablen
• Konditionale Kontrollstrukturen (if, else)
• SASS Unterstützung
• Generierung einer XML Sitemap
• Generierung von allen notwendigen favicons aus einer Datei
• Generierung von Thumbnails für Videos, Audiodateien und PDFs
• Generierung Web-Optimierter Versionen von Bildern
• Generierung eines (Seiten-)Navigationsmenüs anhand von HTML Überschriften und anpassbaren Links
• Einfache Erstellung einer Seite in mehreren Sprachen

Herangehensweise

bUwUma versucht, das Erstellen einer klassischen Webseite (html+css+javascript) nach dem DRY und KISS Prinzip zu ermöglichen. Das bedeutet: Wiederholungen reduzieren und es Simpel halten, damit das Projekt auch in der Zukunft wartbar ist.

Die Erstellung einer Website mit bUwUma ist ähnlich zur Erstellung eines C-Projekts: Man hat ein source (Quell-) und ein build Verzeichnis. Die Quelldateien, also alle HTML-, CSS- und Javascript-Dateien sowie alle Ressourcen wie Bilder und Schriftarten, kommen in das Quellverzeichnis. make baut dann die Webseite und legt sie im build Verzeichnis ab. Dieses kann dann auf den Webserver kopiert werden.

Build-Prozess

Während dem Build-Prozess passiert folgendes:

• HTML Dateien werden vom Präprozessor bearbeitet. Dieser setzt dann sämtliche Variablen ein und bindet zusätzliche Dateien in das Dokument ein (zum Beispiel ein Head, Footer, oder Text in Markdown). Zusätzlich kann aus dem Inhalt ein Seitennavigationsmenü generiert und eingefügt werden. Das resultierende HTML-Dokument wird im build Verzeichnis abgelegt.
• Eine Sitemap im XML Format wird im build Verzeichnis erstellt. Sie enthält Einträge für alle Dateien, in denen der Präprozessor einen sitemap include Befehl gefunden hat.
• SASS Dateien werden von einem SASS-Compiler kompiliert und die resultierenden CSS-Dateien im build Verzeichnis abgelegt.
• Favicons werden aus einem einzigen Bild erstellt. Dazu gehören das klassische favicon.ico sowie favicon.png, apple-touch-icon.png, android-chrome.png und mstile.png Varianten.
• Thumbnails werden für alle gewünschten Dateien im gewünschten Format im build Verzeichnis erstellt
• Web-optimierte Verseionen werden für alle gewünschten Bilder im gewünschten Format im build Verzeichnis erstellt
• Alle anderen Quelldateien (CSS, Javascript, Resourcen wie Bilder und Fonts) werden in das build Verzeichnis kopiert.

Wenn ein Feature nicht gebraucht wird, kann es im Makefile abgeschaltet werden.

Erste Schritte

Um eine Webseite mit bUwUma zu erstellen, muss man nach der Installation der Abhängigkeiten nur ein paar gut dokumentierte Optionen im Makefile anpassen und eine handvoll Befehle des Präprozessors lernen. Diese sollten ziemlich intuitiv sein.

bUwUma ist für Unix entwickelt, benötigt allerdings nur eine geeignete Terminalumgebung. Dadurch kann im Windows Subsystem für Linux (WSL) oder direkt in Windows genutzt werden, sofern die notwendigen Abhängigkeiten installiert sind.

Abhängigkeiten

• GNU Make: [MacOS - Windows - auf fast allen Linux-Distros bereits installiert]
• Posix konforme Shell: z.B. bash oder zsh [bereits vorhanden auf Linux und MacOS]
• Python >=3.10
• Optional:
  • dart-sass: für die Kompilierung von sass
  • imagemagick: für die Generierung von Favicons und das Erstellen von Thumbnails
  • poppler: für die Generierung von Thumbnails für PDFs
  • ffmpeg: für die Erstellung von Thumbnails für Audiodateien [MacOS - Windows - auf fast allen Linux-Distros bereits installiert]

Installation

bUwUma ist auf github und auf meinem gitea verfügbar. Es kann mit git installiert werden:

git clone https://github.com/MatthiasQuintern/bUwUma

Alternativ kann man auch einfach Makefile und html_preprocessor.py von den obigen Links herunterladen.

Konfiguration

1. Pfade im Makefile anpassen. Die Variablen in der Datei selbst dokumentiert
2. make print ausführen und überprüfen, ob die Ausgabe den Erwartungen entspricht
3. make ausführen und zurücklehnen!

nginx

Im Repo liegt zusätzlich liegt eine nginx.conf, in der man nur die root Variable anpassen muss. Anschließend kann die Website mit make start lokal getestet werden.

HTML-Präprozessor

Der HTML-Präprozessor erlaubt die Verwendung von Variablen, if und else Kontrollstrukturen sowie Befehlen wie include, ähnlich wie der C-Präprozessor.

Sämtliche Befehle sind im Readme des GitHub Repos dokumentiert.

Hier das wichtigste kurz zusammengefasst:

• Alle Befehle befinden sich in HTML-Kommentartags, damit das Syntax Highligting nicht durcheinander kommen
• Ein Befehl muss entweder in einem eigenen Kommentar stehen oder in einer eigenen Zeile (in mehrzeiligen Kommentaren)
• Variablen können überall (ohne Kommentartags) benutzt werden mit:

Hier die wichtigsten Befehle:

• include: Fügt eine andere Datei an dieser Stelle ein. Markdown Dateien werden bei diesem Schritt in HTML konvertiert
• set: Weißt einer Variable einen Wert zu

Der include Befehl ermöglicht zum Beispiel einen einzigen HTML-<head> für alle Dateien zu verwenden, indem dieser in einem separaten HTML gespeichert und dann mit include eingefügt wird. Wenn man dann für jede HTML-Datei einen eigenen Titel verwenden will, kann vor dem include Befehl eine Variable gesetzt werden, welche dann im <head><title> Tag genutzt wird.

Erstellen einer Website in mehreren Sprachen

Wenn man eine mehrsprachige Seite möchte, könnte man einfach alle Dateien übersetzen aus einer Sprache übersetzen und in einem anderen Verzeichnis speichern. Das geht vielleicht recht schnell, wenn man aber später etwas beiden Sprachen ändern möchte, z.B. das Layout, das Stylesheet oder Bilder, wird das ziemlich nervig. bUwUma bietet einem zwei bessere Möglichkeiten:

1. Man schreibt eine HTML-Vorlage und zwei oder mehr Dateien, die den eigentlichen Text enthalten (der auch in Markdown geschrieben werden kann!) und fügt diese in die Vorlage ein, wobei die spezielle lang Variable genutzt werden kann sodass man nur eine Kopie der Vorlage benötigt.
2. Man schreibt jeweils eine HTML-Datei für beide Sprachen und eine, welche die Teile enthält, die beide Sprachen gemeinsam haben (z.B. eine Reihe von Bildern), und fügt dann die gemeinsame Datei in die anderen ein.

Natürlich können auch beide Lösungen kombiniert werden.

---

Lizenz