Statische (Dokumentations-) Seiten mit MkDocs und Markdown

Leider habe ich in den letzten Wochen Konstantin bei unserer gemeinsamen Erkundung von Markdown und Zettelkasten-Software, statischen Seiten und zweiten Gehirnen ziemlich alleine gelassen, weil ich zu sehr mit anderen Dingen beschäftigt war. Nun mündet jedoch diese »andere« Beschäftigung in Überlegungen, diese zu publizieren. Und bei der Frage nach dem »wie« und »womit« schließt sich der Kreis doch wieder.

Denn ich möchte gerne als Publikationstool MkDocs ausbuddeln, den freine (BSD-Lizenz), in Python gescnriebenen Generator für statische Seiten mit einem Fokus auf Dokumentationen. Er frißt als Input Markdown (genauer Python Markdown) und eine YAML-Konfigurationsdatei und schreibt auf der anderen Seite (responsive) statische HTML5-Dateien heraus.

Nun ist das letzte Mal, daß ich etwas mit MkDocs anstellte (ich hatte damit meine Processing.py-Seiten veröffentlicht), schon ein paar Jahre her und ich muß daher dringend mein Wissen über MkDocs auf einen aktuellen Stand bringen. Daher habe ich mir ein paar Tutorials aus diesem Jahr herausgesucht:

1. Collins Agbonghama: Building Product Documentation with MkDocs, Sitepoint vom 10. Juni 2022
2. Martin Breuss: Build Your Python Project Documentation With MkDocs, Real Python vom 15. Juni 2022
3. Scott Hampton: Publishing Obsidian.md notes with GitLab Pages, GitLab Blog vom 15. März 2022 (nutzt Material for MkDocs), Obsidian, sollte aber auch mit Logseq und Zettlr funzen

Bisher hatte ich als Theme das bei MkDocs mitgelieferte »ReadTheDocs«-Template genutzt, aber nach einer ersten Durchsicht der neuen Tutorials liegt meine momentane Sympathie bei dem Template »Material for MkDocs« (siehe Screenshot). Es kommt nicht nur mit einer übersichtlichen, dreistufigen Navigation (Kategorie ⇒ Seiten je Kategorie ⇒ Abschnitte je Seite) und vielen Konfigurationsmöglichkeiten, sondern auch mit einer einzigen, vollständigen Installation via pip, die Einrichtung und Updates zu einem Kinderspiel machen.

Allerdings gab es damals noch das Problem, daß Python Markdown bei mathematischen Formeln leicht anders umging als Pandoc-Markdown – also unter Umständen nervige Nacharbeit notwendig war. Schaun wir mal, ob sich hier etwas geändert hat. Ich bin jedenfalls hochmotiviert.

Und sobald die ersten Seiten meiner beiden aktuellen Projekte (oder eines davon) online gehen, werde ich selbstverständlich Bescheid geben. Still digging!

(Kommentieren)