Ansprechende Online-Dokumentationen mit MkDocs erstellen

Inhaltsverzeichnis

Eine gute Dokumentation ist mehr als nur lästiges Beiwerk. Administratoren sollten das Wissen über ihr Netzwerk für Kollegen und die Nachwelt festhalten und Softwareentwickler tun ihren Kunden einen großen Gefallen, wenn sie – am besten auf einer stets aktualisierten Website – eine ausführliche Dokumentation anbieten. Und selbst fürs Heimnetz, fürs Smart Home und die Bastelprojekte lohnt ein solches Handbuch.

Die Software MkDocs gehört zur Gruppe der statischen Seitengeneratoren – ein Schritt zurück zu den Ursprüngen des World Wide Webs. Autoren verfassen die Texte in einer leicht zu lernenden Auszeichnungssprache, in diesem Fall Markdown. MkDocs rendert aus diesen Texten und einer Vorlage fertige HTML-Seiten mit Menü, die man auf einem Webserver ausliefert.

MkDocs-Dokumentationen begegnet man recht häufig, sowohl bei der Dokumentation von Open-Source-, als auch bei kommerzieller Software. Nicht immer erkennt man sie auf den ersten Blick – je nach verwendetem Theme sehen die Ergebnisse sehr unterschiedlich aus. Gluster und Trafik.io sind Beispiele von größeren Softwareprojekten. Viele nutzen das Material-Theme, das Googles Designsprache Material umsetzt. Unter den MkDocs-Themes ist es das mit Abstand ausgereifteste und sehr gut personalisierbar.

Das war die Leseprobe unseres heise-Plus-Artikels "Ansprechende Online-Dokumentationen mit MkDocs erstellen". Mit einem heise-Plus-Abo können sie den ganzen Artikel lesen und anhören.