Zum Inhalt
22. Februar 2026
Keine Werbung, ich erhalte keine Vergünstigungen mit diesem Bericht

Aus "mkdocs" wird "Zensical"

Allgemeine Infos

Diese Seite hier, wie auch (fast) alle meine anderen Seiten, erzeuge ich seit einigen Jahren mit dem statischen Webseitengenerator "mkdocs" für den ich auch Plugins in Python geschrieben habe. Letzte Woche machte man mich darauf aufmerksam, dass während des Build-Prozesses eine Nachricht erscheint, in der darauf hingewiesen wird, dass mkdocs nicht mehr weiter entwickelt wird und durch ein neues Tool namens "Zensical" ersetzt wurde. Das war also keine Absichtserklärung sondern ist bereits ein Fakt.

Bei solchen Nachrichten ist man natürlich ertsmal einigermaßen irritiert, denn das hört sich nach viel Arbeit an. Systemupdates laufen selten ohne irgendwelche Probleme ab und gerade so ein Tool sollte immer einwandfrei arbeiten. Da ich weiß, dass einige Nerds meine Seite aufrufen und sich auch für mkdocs interessieren, berichte ich heute über die Neuerungen.

Ich habe mir das dann mal angeschaut und kann folgendes berichten:

  • "mkdocs" und das Theme "Material" sind quasi zu "Zensical" verschmolzen. Eine sehr gute Idee, denn das Material Theme macht den mkdocs Unterbau überhaupt erst interessant.
  • "Zensical" wird in vier Phasen eingeführt. Die erste Phase, die das nahtlose Betreiben von aktuellen Seiten ermöglichen soll, ist bereits abgeschlossen.
  • "Zensical" kennt keine Plugins - ärgerlich, da mein Plugin "Substitute" gerade erst an den Start gegangen ist :-)
  • Statt Plugins werden in Phase 3 Module über eine einfache API möglich sein - das werde ich mir dann genauer anschauen, wenn es so weit ist.
  • "Zensical" wird statt der Konfiguration mit einer mkdocs.yml Datei eine zensical.toml Datei nutzen. Die hat einen eteas anderen Aufbau, aber die Logik ist in etwa gleich.
  • "Zensical" kann aber auch die vorhandene mkdocs.yml auslesen - ein Umstieg auf die zensical.toml muss nicht sofort erfolgen.
  • Die zensical.toml scheint ein paar Bugs zu haben. Ich habe festgestellt, dass bei einer Änderung der Sprache auf "DE" meine eigenen CSS Klassen nicht mehr eingelesen werden. Einen Grund dafür habe ich nicht finden können.
  • Die Elemente, die bisher nur für zahlende Sponsoren verfügbar waren, werden in Phase 2 hinzugefügt. Da sind interessante Dinge dabei, wie ein Blogsystem, MouseOver Preview etc.
  • In Phase 4 wird mit "Zensical Spark" ein kommerzieller Dienst angeboten, der einer kommerziellen Nutzung kostenpflichtigen Support anbietet. Daraus schließe ich, dass hier ein Bedarf besteht bzw. die Modulfunktionen in Zukunft so einen Support lukrativ erscheinen lassen. Ich könnte mit vorstellen, dass z.B. ShopModule und Theming/Brandung Teil der Module sein werden, die das ganze System immer interessanter machen. "Zensical" selbst ist und bleibt OpenSource.
  • Fazit: mkdocs wird nicht aufgegeben, sondern es wird weiterentwickelt.

Konkretes Vorgehen

Wie steigt man also von "mkdocs/Material" auf "Zensical" um? Das ist sehr einfach. Wer mkdocs nutzt hat schon Python und PIP installiert, da mkdocs sonst gar nicht laufen würde. Zensical wird ganz einfach mit

pip install zensical

installiert.

Statt wir bisher 

mkdocs build

oder

mkdocs serve

für den Live-Server zum Aktualisieren in Echtzeit, nutzt man einfach

zensical build

bzw.

zensical serve

Das klappt ausgesprochen gut. Der build-Prozess lief bei mir ohne Fehler durch. Ich musste nichts in der Konfiguration ändern.

Zwei kleine Fehler gibt es aber schon, die aber vielleicht für manche Seiten gar nicht relevant sein dürften ...

GLIGHTBOX Workround

Für mkdocs/Material gab es ein GLIGHTBOX Plugin. Das konnte man ganz einfach installieren und aktivieren und dann wurden alle Bilder auf den Seiten in einem Lightbox-Overlay angezeigt. Man konnte komfortabel mit den Pfeiltasten durch die Bilder blättern, mit dem Mausrad zoomen etc.

Das funktioniert nicht mehr, denn "Zensical" kennt keine Plugins.

Es gibt aber einen einfachen Workaround.

Zunächst betten wir in der mkdocs.yml die CSS/JS Pfade der GLIGHTBOX mit ein. Immer als aktuellste Version, nicht mehr als Plugin:

extra_css:
    - https://cdn.jsdelivr.net/npm/glightbox/dist/css/glightbox.min.css
extra_javascript:  
    - https://cdn.jsdelivr.net/npm/glightbox/dist/js/glightbox.min.js
    - js/glightbox-init.js

Außerdem benötigen wir eine lokale Datei namens glightbox-init.js die diesen Zweck hat: Dadurch, dass es kein Plugin mehr gibt, welches bei allen Bildern die GLIGHTBOX Klasse zuordnet, müssen wir mit einem JavaScript dies in all unseren Files automatisieren. Die glightbox-init.js hat daher diesen Inhalt:

document.addEventListener("DOMContentLoaded", () => {
    // Alle Bilder im Content-Bereich finden
    const images = document.querySelectorAll(".md-content img");

    images.forEach(img => {
        // Wenn das Bild bereits in einem Link steckt → überspringen
        if (img.parentElement.tagName.toLowerCase() === "a") return;

        // Link um das Bild herum erzeugen
        const link = document.createElement("a");
        link.href = img.src;
        link.classList.add("glightbox");

        img.parentNode.insertBefore(link, img);
        link.appendChild(img);
    });

    // Glightbox starten
    GLightbox({
        selector: ".glightbox"
    });
});

Damit wird allen Bildern die Klasse "GLIGHTBOX" zugeordnet und Bilder werden dann in dem Overlay geöffnet.

Das klappt einwandfrei.

Ich möchte nicht, dass die Texte auf meiner Seite als Hyperlinks unterstrichen werden, was aber jetzt standardmässig der Fall ist. Das lässt sich leicht umgehen, in dem man eine extra.css mit lädt, in der dieser Inhalt steckt:

a {
    text-decoration: none !important;
}

Und ich wollte die Menues der Sidebar etwas kompakter erscheinen lassen. Das erreicht man mit 

.md-nav__link {
    font-size: 0.6rem;
    font-weight: bold;
    padding-bottom: 2px;
    padding-top: 2px;  
}

.md-nav__title {
    font-weight: 700;
    font-size: 0.7rem;
    color: darkred;
}

Beide Klassen kann man nach den eigenen Bedürfnissen anpassen.

Hinweis: Diese Seite www.killert.de wurde bereits mit "Zensical" erzeugt.

Alle Infos zu "Zensical": https://zensical.org/
Alle Infos zur Roadmap und welche Features (noch nicht) funktionieren: https://zensical.org/about/roadmap/