Making of www.killert.de

Auf diesen Seiten erkläre ich, wie ich diese Seiten erstellt habe und welche Hintergrund der Wechsel zu mkdocs und Material hatte. Es ist eine Schritt-für-Schritt Anleitung und sollte für halbwegs technisch versierte Menschen keine Verständnisprobleme verursachen.

Vorgeschichte

Eigentlich ist Rapidweaver auf dem Macintosh das beste Programm, um Webseiten zu bauen und zu pflegen. Da ich aber keinen Mac mehr und ich an den Apple-Produkten den Wegwerf-Faktor - gibt es keine Updates mehr, kann man bestenfalls noch ein Linux auf den Rechnern installieren - brauchte ich eine Lösung, die unabhängig von der Plattform ist. Da war es zunächst naheliegend, ein Content-Management-System (CMS) wie Wordpress zu nutzen. Das habe ich auch gemacht. Was ich zunächst als Erleichterung angesehen habe entpuppte sich als böse Falle - die Nutzung diverser Plugins in Wordpress haben bei mir irgendwann nur noch Probleme verursacht. Man verliert irgendwann die Kontrolle über die Struktur und die Verknüpfung der Inhalte. Das passt mir gar nicht.

Vor einiger Zeit hatte ich auch schon Software zur Generierung statischer Seiten angeschaut. Am besten mit Markdown als Grundlage. Das war schon vielversprechend, aber noch nicht ausgereift. Das ist bei mkdocs aber der Fall. mkdocs selbst ist eine Anwendung in Python, die aus einzelnen Markdown-Dateien, von denen jede eine Seite der Homepage repräsentiert, eine Webpage zusammenbaut. Das hört sich jetzt kompliziert an, ist aber gar nicht so schwierig zu verstehen.

Wichtigste Grundlage: Markdown

Markdown ist allgegenwärtig. Es ist eine Auszeichnungssprache, mit der man sehr schnell grundlegend formatierten und strukturierten Text schreiben kann. Hinter der Darstellung des Textes steckt ein Stylesheet, also eine austauschbare Formatvorlage. Das bedeutet, dass man einen Markdowntext mühelos nach HTML, PDF oder WORD exportieren kann.

Links die Markdown Datei und rechts in Echtzeit die Formatierung im Preview

Alle wichtigen Grundlagen zu Markdown finden sie hier ⧉. Als Editor kann man jeden beliebigen Editor verwenden - insbesondere, wenn Sie mit mkdocs beginnen würde ich Visual Studio Code oder Notepad++ empfehlen - beides kostenfrei und längst nicht auf Markdown beschränkt. Bei beiden müssen Sie eine Markdown Erweiterung installieren. Im späteren Teil dieser Anleitung konzentriere ich mich auf Visual Studio Code ⧉. Um mit Markdown selbst "herumzuspielen" empfehle ich besonders am Anfang den kostenfreien Webeditor Stackedit ⧉ bei dem Sie sofort drauflosschreiben können.

Markdown wird stetig erweitert. Eine Erweiterung finde ich besonders bemerkenswert: mit "Mermaid" können Sie Diagramme schreiben, die dann automatisch als Vektorgrafiken gerendert werden. Das sieht dann so aus:

In diesem Beispiel wird in Markdown ein Mermaid Diagram gerendert.

Weitere Voraussetzungen

Um mit mkdocs arbeiten zu können benötigen Sie Python. Python ist eine weitverbreitete Programmiersprache, die immer populärer wird. Sie müssen aber keine Programmierfähigkeiten, sollten aber eine Eigenart von Python kennen: Im Gegensatz zu z.B. C oder C++ erkennt der Compiler von Python Code-Blöcke nicht anhand von Klammern, sondern anhand von Einrückungen. Die Konfigurationsdatei einer mkdocs Seite ist eine Datei, die in Python verarbeitet wird, d.h. es ist von entscheidender Bedeutung, welche Einrückungen dort gesetzt sind. Sie sollten grundsätzlich immer alle Einrückungen genauso übernehmen, wie sie vorgegeben sind.