Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Zensical
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Zensical ist ein Generator für statische Websites, der aus Markdown-Dateien eine fertige Dokumentations-Website mit Suche, Navigation und hellem und dunklem Design baut. Er stammt von den Entwicklern von Material for MkDocs, ist teilweise in Rust geschrieben und baut deshalb sehr schnell. Vorhandene MkDocs-Projekte kann er direkt übernehmen.
Vorbemerkungen
- Keine Installation über apt: Ubuntu hat kein Paket für Zensical. Es wird als Python-Programm mit
pipxinstalliert, wie es die Anleitung Python für Kommandozeilenprogramme empfiehlt.pipxlegt dafür automatisch eine eigene virtuelle Umgebung an, sodass Zensical nichts an der Python-Installation von Ubuntu ändert. - Version: Getestet mit Zensical 0.0.65 und Python 3.14 unter Ubuntu 26.04. Zensical ist noch jung: Einstellungen und Befehle können sich zwischen Versionen ändern.
- Verhältnis zu MkDocs: Zensical liest seine Einstellungen aus
zensical.toml, versteht aber auch diemkdocs.ymleines vorhandenen MkDocs-Projekts.
Installation
1. Paketlisten aktualisieren
Damit apt die aktuelle Version von pipx kennt.
sudo apt update
2. pipx installieren
pipx installiert Python-Programme jeweils in eine eigene virtuelle Umgebung und macht ihren Befehl trotzdem überall verfügbar.
sudo apt install pipx
Prüfen: Die Versionsnummer erscheint, z. B. 1.8.0.
pipx --version
3. Zensical installieren
Lädt Zensical von https://pypi.org und legt den Befehl zensical in ~/.local/bin ab.
pipx install zensical
Prüfen: Die Versionsnummer erscheint, z. B. 0.0.65.
zensical --version
Meldet das Terminal zensical: Kommando nicht gefunden, fehlt ~/.local/bin im Suchpfad. pipx ensurepath trägt den Ordner ein. Danach ein neues Terminal öffnen.
Erstes Projekt
4. Projekt anlegen
Legt den Ordner ~/zensical-test mit einer Beispielseite, einer Einstellungsdatei und einer Vorlage für die automatische Veröffentlichung auf GitHub Pages an.
zensical new ~/zensical-test
5. In den Projektordner wechseln
Alle weiteren Befehle arbeiten im Projektordner.
cd ~/zensical-test
Prüfen: Der Ordner enthält zensical.toml und den Ordner docs mit index.md und markdown.md. Der versteckte Ordner .github enthält die Vorlage für GitHub Pages.
ls -A
6. Einstellungsdatei schreiben
Die mitgelieferte zensical.toml ist englisch und enthält viele Beispiele. Diese Fassung ist kürzer und stellt die Oberfläche auf Deutsch um.
nano zensical.toml
Lösche den bisherigen Inhalt: Alt+\ springt an den Anfang, Alt+A beginnt eine Markierung, Alt+/ springt ans Ende, Strg+K schneidet alles aus. Füge dann diesen Inhalt ein (Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:
[project]
site_name = "Meine Dokumentation"
site_url = "http://localhost:8000/"
nav = [
{ "Start" = "index.md" },
{ "Erste Seite" = "erste-seite.md" },
]
[project.theme]
language = "de"
features = [
"content.code.copy",
"navigation.footer",
"search.highlight",
]
[[project.theme.palette]]
media = "(prefers-color-scheme: light)"
scheme = "default"
toggle.icon = "lucide/moon"
toggle.name = "Dunkles Design"
[[project.theme.palette]]
media = "(prefers-color-scheme: dark)"
scheme = "slate"
toggle.icon = "lucide/sun"
toggle.name = "Helles Design"
Was die Einträge bedeuten:
site_name– der Name der Website, er steht oben links und im Titel jeder Seite.site_url– die spätere Adresse der Website. Zensical braucht sie z. B. für die Sitemap.nav– die Navigation: links der angezeigte Name, rechts die Datei im Ordnerdocs.language = "de"– Suche, Schaltflächen und Hinweise erscheinen auf Deutsch.features– Zusatzfunktionen.content.code.copysetzt eine Kopier-Schaltfläche an jeden Codeblock,navigation.footerzeigt unten Links zur vorigen und nächsten Seite,search.highlighthebt Suchbegriffe hervor.[[project.theme.palette]]– ein helles und ein dunkles Design. Welches zuerst gilt, richtet sich nach der Einstellung des Betriebssystems. Über das Symbol oben rechts lässt sich umschalten.
7. Nicht mehr benötigte Beispielseite löschen
Die Datei markdown.md steht nicht mehr in der Navigation. Zensical würde sie trotzdem mit ausgeben.
rm docs/markdown.md
8. Eine neue Seite anlegen
Legt die Seite an, die in nav als „Erste Seite“ eingetragen ist.
nano docs/erste-seite.md
Füge diesen Inhalt ein, speichere mit Strg+O und Enter und beende nano mit Strg+X:
# Erste Seite
Das ist meine **erste Seite** mit Zensical.
```bash
zensical build
```
9. Vorschau starten
Baut die Website und stellt sie unter http://localhost:8000 bereit. Speicherst du eine Datei im Ordner docs, baut Zensical die Seite neu. Nach dem Neuladen im Browser ist die Änderung zu sehen.
zensical serve
Prüfen: Im Terminal steht Serving /home/…/zensical-test/site on http://localhost:8000. Im Browser zeigt http://localhost:8000/erste-seite/ die neue Seite. Über dem Codeblock erscheint beim Darüberfahren die Schaltfläche In Zwischenablage kopieren.
10. Vorschau beenden
Drücke im Terminal Strg+C. Die Vorschau hört auf, der Ordner bleibt unverändert.
11. Fertige Website bauen
Erzeugt die fertige Website im Ordner site. Diesen Ordner kann man auf jeden Webserver kopieren, z. B. nach nginx, oder mit gh-pages veröffentlichen. --strict bricht bei Warnungen ab, etwa bei Links auf Seiten, die es nicht gibt.
zensical build --strict
Prüfen: Die Ausgabe endet mit Build finished in …, und die Startseite ist vorhanden.
ls site/index.html
Vorhandenes MkDocs-Projekt bauen (optional)
12. MkDocs-Projekt mit Zensical bauen
Wechsle in ein Projekt, das eine mkdocs.yml hat, z. B. aus der Anleitung MkDocs. -f sagt Zensical, welche Einstellungsdatei es lesen soll. Das Ergebnis landet wie bei MkDocs im Ordner site.
zensical build -f mkdocs.yml
Prüfen: Die Ausgabe endet mit Build finished in …. Zensical unterstützt noch nicht alle Erweiterungen von MkDocs. Meldet es Probleme, hilft die Seite https://zensical.org/docs/compatibility/mkdocs/.
Aktualisieren
1. Neue Version installieren
pipx aktualisiert Zensical in seiner eigenen Umgebung.
pipx upgrade zensical
Prüfen: zensical --version zeigt die neue Versionsnummer.
Deinstallieren
1. Testprojekt entfernen
Löscht den Beispielordner samt gebauter Website.
rm -rf ~/zensical-test
2. Zensical entfernen
Entfernt Zensical samt seiner virtuellen Umgebung.
pipx uninstall zensical
Prüfen: Der Befehl zensical wird nicht mehr gefunden.
zensical --version
3. pipx entfernen (optional)
Nur ausführen, wenn du keine anderen Programme mit pipx installiert hast. pipx list zeigt, welche es gibt.
sudo apt purge pipx
sudo apt autoremove
Quellen und Lizenz
- Offizielle Dokumentation: https://zensical.org/
- Lizenz: Zensical steht unter der MIT.
Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).
Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.