Site-Build

Entwickelt: 2023

Es gibt ein paar mit MkDocs gebaute Dokumentationen, die ich gern auf meinem Webserver (wieder mal ein Raspi - siehe Raspi/Server/Webserver) stets aktuell verfügbar haben möchte. Die liegen jeweils in einem Gitlab-Repo und sind da nur als Markdown-Sources verfügbar.

Die Aufgabe:

  • Hole den aktuellen Stand vom Gitlab-Server
  • Erzeuge eine HTML-Seite daraus
  • Kopiere die Seite auf Deinen Webserver

Zuerst mal brauchst Du Python, das sollte auf jedem Rechner mit einem richtigen Betriebssystem (also Linux) eh installiert sein. Wenn nicht: Hol es Dir über die Paketverwaltung der Distribution. Dann installierst Du MkDocs inkl. einiger Zusatzpakete: 

jan@jack:~/bin$ sudo pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin
Jetzt kann es losgehen, das Script ist so winzig, dass ich es hier direkt reinhänge: 
 1  #! /bin/bash
 2  # update static sites on server from git repos
 3  # (c) software@jan.trippler.de 2023
 4
 5  # the development base dir on client
 6  export DEV_BASE=/path/to/projects
 7  # access and path for web sites at the server
 8  export WEB_SRV_BASE=pi@walter:/srv/www
 9
10  # the repos to update - repo-folder:site-dir:remote-dir
11  declare -a doc_repos=( "repo-1:site/:webdir-1" "repo-2:site/:webdir-2" );
12
13  # walk through repos, pull, build and transfer to server
14  for repo in ${doc_repos[@]}; do
15    repo_dir=`echo "$repo" | cut -f1 -d':'`
16    site_dir=`echo "$repo" | cut -f2 -d':'`
17    remote_dir=`echo "$repo" | cut -f3 -d':'`
18    cd $DEV_BASE/$repo_dir
19    # pull from git server
20    git pull origin develop
21    # find mkdocs dir
22    cd $(dirname $(find . -name mkdocs.yml))
23    # build
24    mkdocs build --clean
25    # transfer to server
26    rsync -aq --delete $site_dir --stats $WEB_SRV_BASE/$remote_dir
27  done
28
29  exit 0
  • Zeile 6: Das Projekt-Basisverzeichnis
  • Zeile 8: User, Server und Basispfad zu den Webverzeichnissen
  • Zeile 11: Die Repositories (Projektverzeichnisse) als Array mit der Syntax Verzeichnis:Site-Verzeichnis (hier landet das HTML):Zielverzeichnis Webserver
Das Script nimmt die Array-Elemente auseinander (Zeilen 15...17) - ja, das hätte man auch mit bash-Mitteln erledigen können. Dann holt es sich in den Repo-Verzeichnissen per git pull den aktuellen Stand vom Server. Dann wird in den Pfad gewechselt, in dem die mkdocs.yml liegt und dort die Doku über mkdocs build erzeugt. Zuletzt wird der Inhalt des im Array definierten Site-Verzeichnis per rsync auf den Webserver übertragen.