Zensical unter Windows 11

Zensical ist ein Generator für statische Webseiten, der auf die Erstellung von Projektdokumentationen spezialisiert ist. Die Quelldateien der Dokumentation werden in Markdown geschrieben und mit einer einzigen TOML-Textdatei konfiguriert. Dieser Blog-Artikel zeigt Euch, wie man Zensical installiert, konfiguriert und benutzt.

Einführung

Zensical ist ein moderner Open-Source-Generator für technische Dokumentationen. Er wandelt in Markdown geschriebene Dokumente in eine statische Webseite um. Die erzeugte Webseite kann auf praktisch jedem Webserver bereitgestellt werden. Eine Datenbank, PHP oder eine andere serverseitige Laufzeitumgebung wird nicht benötigt.

Zensical ist in Rust und Python implementiert und steht unter der MIT-Lizenz.

Von MkDocs zu Zensical

MkDocs hat sich über viele Jahre als einfacher und leistungsfähiger Generator für Markdown-basierte Projektdokumentationen etabliert. Mit Material for MkDocs entstand darauf aufbauend ein umfangreiches Theme, das MkDocs um zahlreiche Funktionen für Navigation, Suche, Darstellung und technische Dokumentationen erweitert.

Am 5. November 2025 stellte das Material-for-MkDocs-Team mit Zensical einen neuen, von Grund auf entwickelten Static-Site-Generator vor.

Ein wesentlicher Auslöser für die Neuentwicklung waren unterschiedliche Vorstellungen zwischen den Entwicklern von MkDocs und Material for MkDocs über Wartung, technische Weiterentwicklung und Governance des MkDocs-Projekts.

Das Material-Team kritisierte insbesondere den zeitweisen Stillstand von MkDocs 1.x sowie architektonische Einschränkungen und sah die starke Abhängigkeit von MkDocs zunehmend als Risiko. Mit der wieder aufgenommenen Entwicklung von MkDocs 2.0 kamen zudem grundlegende Änderungen hinzu, die teilweise nicht mit Material for MkDocs und bestehenden Erweiterungen kompatibel sind (mehr Hintergründe dazu im Blog von Material for MkDocs).

Das Material-Team entschied sich deshalb, die gemeinsame technische Basis zu verlassen und mit Zensical einen eigenen Static-Site-Generator zu entwickeln. Material for MkDocs wurde daraufhin in den Wartungsmodus versetzt, während die aktive Weiterentwicklung nun hauptsächlich bei Zensical stattfindet.

Zensical in der Praxis

Wir werden jetzt Folgendes tun:

1. Python installieren.

2. Eine lokale Python-Umgebung einrichten und Zensical installieren.

3. Ein erstes eigenes Zensical-Projekt erstellen und testen.

Python installieren

Python ist eine interpretierte Programmiersprache für alle möglichen Zwecke. Wir wollen hier allerdings nicht in Python programmieren, sondern benötigen die Laufzeitumgebung für das Ausführen von Zensical.

Zur Installation unter Windows gehe wie folgt vor:

1. Lade die aktuelle Windows-Version von Python herunter. In der Regel wird dies das Setup-Paket für Windows 64-Bit sein (z. B. python-3.14.7-amd64.exe).

   

2. Starte das Setup-Paket auf Deinem Computer. Markiere unbedingt die Option Add Python to PATH und wähle dann Install Now.

   

3. Ist die Installation fertig, kannst Du den Setup-Dialog mit Close schließen.

   

Zum Testen der Python-Umgebung starte PowerShell und tippe Folgendes ein:

python --version

Dieser Befehl sollte eine Ausgabe wie diese hier produzieren:

Python 3.14.7

Jetzt testen wir noch die Installation der Python-Paketverwaltung pip:

pip --version

Dieser Befehl sollte eine Ausgabe wie diese hier produzieren:

pip 26.2.1 from C:\Users\frank\AppData\Local\Programs\Python\Python314\lib\site-packages\pip (python 3.14)

Mein erstes Zensical-Projekt

Wir bleiben in PowerShell und erstellen zunächst eine lokale Python-Umgebung:

python -m venv .venv
.venv\Scripts\activate
pip install zensical

Anschließend erzeugen wir mit einem einzigen Befehl ein neues Zensical-Projekt:

zensical new .

Das Ergebnis schauen wir uns etwas genauer an:

.
├── docs\
│   ├── index.md
│   └── markdown.md
└── zensical.toml

Folgende Dateien wurden erzeugt:

• Die Datei zensical.toml enthält die Konfiguration sowie das Inhaltsverzeichnis Deines Zensical-Projekts.
• Im Unterordner docs befinden sich die Markdown-Dateien index.md und markdown.md mit Beispieltext.

OK, und wie kann ich aus diesen Dateien eine Webseite generieren?

Dazu wechseln wir wieder zu PowerShell und starten den Build-Prozess von Zensical:

zensical build

Das Ergebnis sieht in etwa so aus:

Build started
No issues found
Build finished in 0.51s

Die generierte Webseite liegt also im Unterordner site. Beachte: Bei jedem erneuten Build wird der Inhalt von site überschrieben.

Jetzt wollen wir uns unser Projekt im Webbrowser anschauen. Zensical stellt dafür einen kleinen Webserver zur Verfügung, den wir wie folgt aktivieren können:

zensical serve --open

Das Ergebnis sieht in etwa so aus:

Serving \\?\C:\zensical\test-project\site on http://localhost:8000
Build started
No issues found

Unsere generierte Webseite wird automatisch in Deinem Webbrowser unter der URL http://localhost:8000/ geöffnet:

Der eingebaute Webserver von Zensical hat noch einen weiteren Vorteil. Er reagiert auf Änderungen in der Datei zensical.toml und im Unterordner docs, indem er automatisch einen erneuten Build anstößt. Das bedeutet, dass inhaltliche Änderungen nach dem Speichern der Dateien unmittelbar im Webbrowser betrachtet werden können.

Du kannst jetzt mit Deinem Projekt weiter herumspielen, Texte verändern, neue Kapitel anlegen, die Struktur verändern und alle möglichen Konfigurationsparameter ausprobieren. Weitere Details zu Zensical findest Du u. a. hier:

• Zensical Setup
• Zensical Authoring
• Zensical Studio

Das Arbeiten mit Markdown macht mehr Spaß, wenn der Texteditor die Syntax farblich hervorheben kann. Der Standardeditor von Windows ist dazu nicht in der Lage. Zu empfehlende Open-Source-Alternativen wären:

• Visual Studio Code
• Notepad++

Ein Zensical-Projekt publizieren

Möchtest Du Dein Zensical-Projekt auf einem öffentlichen Webserver publizieren, musst Du lediglich alle Dateien und Unterordner unterhalb von site kopieren. Da es sich ausschließlich um statische Dateien (HTML, CSS, JavaScript etc.) handelt, muss Dein Webserver keine zusätzlichen Laufzeitumgebungen (z. B. PHP oder Node.js) installiert haben.

Da das manuelle Kopieren mit der Zeit lästig wird, sollte man das Publizieren automatisieren. Das Stichwort für Besserwisser ist hier Continuous Deployment. Wer den Quellcode seines Zensical-Projekts auf GitHub liegen hat, kann dies beispielsweise sehr elegant per GitHub Actions umsetzen.

Ein Beispiel für eine mit Zensical implementierte Dokumentation inklusive GitHub Actions ist die OpenT8-Dokumentation.

Zensical aktualisieren

Zensical wird kontinuierlich weiterentwickelt. Es macht also Sinn, von Zeit zu Zeit nach Updates Ausschau zu halten und diese einzuspielen. Dafür ist wieder die Python-Paketverwaltung pip zuständig.

Zunächst soll überprüft werden, ob ein Update notwendig ist. Tippe dazu in der Eingabeaufforderung Folgendes ein:

pip list --outdated

Dieser Befehl listet alle Python-Pakete auf, für die es bereits eine neuere Version gibt. Das Ergebnis könnte beispielsweise wie folgt aussehen:

Package            Version Latest Type
------------------ ------- ------ -----
pymdown-extensions 11.0.2  12.1   wheel
zensical           0.0.60  0.0.64 wheel

Uns interessieren vor allem die Pakete zensical und pymdown-extensions. Für beide gibt es in diesem Beispiel etwas Neues.

Für das Einspielen der Updates tippe Folgendes ein:

pip install --upgrade zensical pymdown-extensions