MkDocs für die Erstellung eines Wikis
MkDocs ist ein Tool zum Erstellen von statischen Websites für Dokumentationen. Es verwendet Markdown-Dateien und wandelt sie in eine HTML-basierte Dokumentation um. MkDocs bietet eine einfache Einrichtung, Echtzeit-Vorschau und anpassbare Themes, wie das Material-Theme. Es eignet sich ideal für technische Dokumentationen und Wikis.
Im Artikel MkDocs Installieren und ein erstes Projekt erstellen habe ich bereits erklärt, wie man mkdocs installieren kann. In dieser Dokumentation zeige ich, wie dieses Wiki aufgebaut ist und Automatisch aktualisiert wird.
Installation von mkdocs
Prüfen of pipx installiert ist, wenn dies nicht der Fall ist dann installieren wir es mit apt. Für andere Systeme wie Redhat muss apt mit yum bzw. dnf ersetzt werden.
pipx --version 2>/dev/null || sudo apt update && sudo apt install pipx
Nach der Installation von pipx ist es wichtig, sicherzustellen, dass der PATH angepasst ist. Dabei wird /home/$LOGNAME/.local/bin zur PATH Variable aufgenommen.
python3 -m pipx ensurepath
exec $SHELL # Neu starten, damit PATH aktualisiert wird
Dann installieren wir mkdocs mit pipx.
pipx install mkdocs || echo "Failed to install mkdocs." >&2
Somit hätten wir schon ein funktionierendes mkdocs. Wir erweitern mkdocs mit dem Theme material und einigen weiteren Plugins. Der folgende Befehl installiert das mkdocs-material Theme.
pipx inject mkdocs mkdocs-material --include-deps --include-apps || echo "Failed to install mkdocs-material." >&2
Zusätzliche Plugins für mkdocs installieren, wie in diesem Beispiel (mkdocs-macros-plugin, mkdocstrings, mkdocs-git-revision-date-localized-plugin, mkdocs mkdocs-git-committers-plugin-2, mkdocs-git-authors-plugin) installieren wir wie folgt.
pipx inject mkdocs mkdocs-macros-plugin --include-deps --include-apps || echo "Failed to install mkdocs-macros-plugin." >&2
pipx inject mkdocs mkdocstrings || echo "Failed to install mkdocstrings." >&2
pipx inject mkdocs mkdocs-git-revision-date-localized-plugin --include-deps --include-apps || echo "Failed to install mkdocs-git-revision-date-localized-plugin." >&2
pipx inject mkdocs mkdocs-git-committers-plugin-2 --include-deps --include-apps || echo "Failed to install mkdocs-git-committers-plugin-2." >&2
pipx inject mkdocs mkdocs-git-authors-plugin --include-deps --include-apps || echo "Failed to install mkdocs-git-authors-plugin." >&2
Alle installierten mkdocs Pakete lassen wir uns mit pipx list anzeigen.
pipx list
venvs are in /vol/box01/home/$LOGNAME/.local/pipx/venvs
apps are exposed on your $PATH at /vol/box01/home/$LOGNAME/.local/bin
package mkdocs 1.6.1, installed using Python 3.11.2
- ghp-import
- hjson
- markdown_py
- mkdocs
- mkdocs-get-deps
- normalizer
- pybabel
- pygmentize
- watchmedo
Wer dies alles in einem Rutsch installieren möchte, kann das folgende Installationsskript für mkdocs verwenden.
#!/bin/bash
# Prüfen und pipx installieren
if ! command -v pipx >/dev/null 2>&1; then
if [ -f /etc/debian_version ]; then
sudo apt install pipx
elif [ -f /etc/fedora-release ]; then
sudo dnf install pipx
elif [ -f /etc/arch-release ]; then
sudo pacman -S pipx
else
echo "Unsupported distribution. Install pipx manually." >&2
exit 1
fi
python3 -m pipx ensurepath
exec $SHELL
fi
# mkdocs installieren
pipx install mkdocs || { echo "Failed to install mkdocs." >&2; exit 1; }
# Theme Material für mkdocs
pipx inject mkdocs mkdocs-material --include-deps --include-apps || {
echo "Failed to install mkdocs-material." >&2
exit 1
}
# Zusätzliche Plugins
pipx inject mkdocs mkdocs-macros-plugin --include-deps --include-apps || exit 1
pipx inject mkdocs mkdocstrings || exit 1
pipx inject mkdocs mkdocs-git-revision-date-localized-plugin --include-deps --include-apps || exit 1
pipx inject mkdocs mkdocs-git-committers-plugin-2 --include-deps --include-apps || exit 1
pipx inject mkdocs mkdocs-git-authors-plugin --include-deps --include-apps || exit 1
# Übersicht anzeigen
pipx list
# EOF
mkdocs zusammen mit Gitbucket als Backend einrichten
Für unser Wiki was Gitbucket als Backend nutzt richten wir uns unter /var/www/wiki folgende Verzeichnisstruktur ein.
wiki
|
+- htdocs
|
+- mkdocs
|
+- repo
Beschreibung der Verzeichnisse
| Verzeichnis | Beschreibung |
|---|---|
| htdocs | Statiche HTML Wiki |
| mkdocs | MkDocs Entwicklungsumgebung |
| repos | Git Repository von docs/ |
Mit mkdocs erstellen wie die Verzeichnisse für unser Wiki.
mkdir -p /var/www/wiki/{repo,mkdocs,htdocs}
Dann wechseln wir in das Verzeichnis mkdocs, was wir erstellt haben und klonen und das <user>/wiki_mkdocs Repository.
cd /var/www/wiki/mkdocs/
git clone ssh://git@gitbucket.example.com:8081/<user>/wiki_mkdocs.git .
Bevor wir mkdocs starten, können wir in bin/Config.inc.sh nocht den Port und das Interface einrichten.
vi bin/startup.sh
...
# Interface or ip address
cfg[interface]="localhost"
# mkdocs port (default: 8000)
cfg[port]=8001
Bei dieser gelegenheit sollten wir gleich noch die site_url und repo_url in der mkdocs.yml anpassen.
# Project informations
site_name: IT Knowledge Base
site_url: https://mkdocs.example.com/
# Git Repository
repo_url: https://gitbucket.example.com/<user>/wiki_docs
repo_name: <user>/wiki_docs
edit_uri: edit/master/
Nun müssen wir noch das selbst erstellte mkdocs Plugin add_postmeta bauen.
cd include/plugins/ && pipx inject mkdocs .
Damit mkdocs unabhängig von der aktuellen Bash Session läuft, erstellen wir eine Screen Session wiki in welcher wir mkdocs starten.
screen -S wiki
Nun können wir in der Screen Session das Start Skript /var/www/wiki/mkdocs/bin/startup.sh starten.
/var/www/wiki/mkdocs/bin/startup.sh
Mit der Tastenkombination Ctrl+A+D verlassen wir die aktuelle Screen Session.
Wenn wir nun auf der in site_url definierten Seite (https://mkdocs.example.com/) gehen sollten wir nun ein Fertig installiertes MkDocs mit einer Hauptseite sehen.
Damit wir die Daten in unser Wiki bekommen, bearbeiten wir das Skript bin/Config.inc.sh und passen die Variable cfg[basedir] an unseren Pfad an, wo dich die Verzeichnisse repor, mkdocs und htdocs befinden.
vi bin/wikiupdate.sh
....
# Path to the basename of the wiki directory
cfg[basedir]="/var/www/wiki"
Dann gehen wir in unserem repo Vzerzeichnis und klonen das <user>/wiki_docs Verzeichnis.
cd /var/www/wiki/repo && git clone ssh://git@gitbucket.example.com:8081/<user>/wiki_docs.git .
Im Skript /var/www/wiki/mkdocs/bin/wikiupdate.sh setzen wir die Variable cwd zum Verzeichnispfad wo die mkdocs.yml sich befindet. Dieses Skript verwenden wir dann als Webhook Skript.
Dazu gehen wir auf https://webhook.example.com/login, melden uns an und erstellen uns einen Webhook, der dieses Skript ausführt.
Info
Einen Webhook in https://webhook.example.com/ einrichten, folgt in einer weiteren Dokumentation.