mkdocs unter OpenBSD
Bisher habe ich meine Blogs unter Hugo und Pelican geschrieben und bin mit beiden statischen Generatoren absolut zufrieden. Dennoch schaue ich mich ab und zu nach Alternativen um und dabei bin ich auf mkdocs gestossen. Erschien mir interessant zu sein, auch weil es für reine Dokumenation gut einsetzbar ist.
Das mkdocs Framework ist in Python geschrieben, was mir schon mal sehr sympathisch ist. Bislang hab ich es auf mehreren Betriebssystem installiert: OpenBSD, NetBSD, DragonFly BSD und MidnightBSD. Läuft auf all diesen Platformen einwandfrei,
Im Folgenden beschreibe ich in aller Kürze die einzelnen Schritte für die Installation von mkdocs:
Zuerst als root Python und py-pip installieren. Ich habe Python3.12 dafür genommen.
# pkg_add python3.12 py3-pip
Dann ein Projekt-Verzeichnis erstellt und dorthin gewechselt:
mkdir ~/work/projekt1
cd ~/work/projekt1
In diesem neuen Verzeichnis wird eine virtuelle Umgebung in einem Verzeichnis namens venv eingerichtet. Der Name des Verzeichnisses ist natürlich frei wählbar:
python3 -m venv venv
Nun kann diese virtuelle Umgebung aktiviert werden:
source venv/bin/activate
Ab jetzt zeigt ein (venv) vor dem normalen Prompt an, dass die virtuelle Umgebung aktiv ist. Der Prompt könnte dann z.B. so aussehen:
(venv) $berni@raspi56 ~/work/projekt1 $_
Zum Schluss muss natürlich noch mkdocs und material installiert werden:
pip install --upgrade pip
pip install mkdocs mkdocs-material
Beachte, dass die Installation innerhalb der virtuellen Umgebung erfolgen muss. Klappt aber auch sonst nicht.
Jetzt kann mit der eigentlichen Arbeit am Blog oder der Dokumentatio begonnen werden.
mkdocs new projektname erstellt ein Skelett für ein neues Projekt. Bei mir war es meist so, dass ich vorhandene Pelican-Projekte übernommen habe und die Posts, Pages und Images ins mkdocs-Verzeichnis kopiert habe. Anschliessen dann die mkdocs.yml angepasst.