Explanation
Was ist mdBook?
Tool zur Erstellung von Dokumentations-Webseiten mithilfe von Markdown
mdBook ist ein Static Site Generator der Markdown-Dateien in eine statische HTML-Webseite umwandelt. [1]
- entwickelt in Rust
- Grundlage der offiziellen Rust Dokumentation (Rust Book)
- Dokumentation wird in Markdown geschrieben
- Ausgabe als statische HTML-Webseite
Welche Probleme löst mdBook?
Dokumentation ohne mdBook:
README.md
docs/
install.md
usage.md
tutorial.md
...
Herausforderungen
- viele einzelne Markdown-Dateien
- keine zentrale Navigation
- keine integrierte Suche
- uneinheitliche Darstellung
Dokumentation mit mdBook
mdBook erzeugt aus den Markdown-Dateien automatisch:
- Navigation zwischen den Seiten
- Inhaltsverzeichnis
- Suchfunktion
- einheitliches Layout
- statische HTML-Ausgabe
Dadurch entsteht eine übersichtliche und leicht wartbare Dokumentation
Typische Einsatzgebiete
- Software-Dokumentation
- Entwicklerhandbücher
- Tutorials
- Vorlesungsunterlagen
Wann lohnt sich mdBook?
mdBook eignet sich besonders dann, wenn:
- die Zielgruppe Entwickler sind
- die Dokumentation eng mit Rust-Code verzahnt ist
- eine wartbare, versionierbare Doku gefragt ist
- keine schwere Infrastruktur erwünscht ist
Diataxis
Dieses Buch folgt dem Diátaxis-Framework, das Dokumentation in vier Typen strukturiert:
| Diataxis-Typ | Inhalt |
|---|---|
| Explanation | Was ist mdBook und warum existiert es? |
| Tutorial | Installation und Projektaufbau Schritt für Schritt |
| How-to Guide | Lokalen Server starten und Workflow |
| Reference | typische bzw. mögliche Befehle |
Stärken von mdBook
- Einfaches Markdown-basiertes Book
- Integrierte Suchfunktion und Navigation ohne Konfigurationsaufwand
- Rust-Doctests direkt aus der Dokumentation ausführbar (
mdbook test) - Statische HTML-Ausgabe
- Läuft vollständig lokal – keine externe Abhängigkeit, keine Cloud
- Leichtgewichtig und schnell dank Rust-Implementierung
Schwächen von mdBook
- Primär auf das Rust-Ökosystem ausgerichtet
- Wenig Layout-Flexibilität im Vergleich zu anderen Static Site Generatoren
- Markdown-only – kein Support für komplexe Styles oder interaktive Inhalte
mdBook vs. JupyterBook
JupyterBook ist ein alternatives Dokumentationstool, das Jupyter Notebook-Dateien unterstützt und sich besonders für wissenschaftliche Publikationen eignet.
| Kriterium | mdBook | JupyterBook |
|---|---|---|
| Zielgruppe | Rust-Entwickler, Programmierer | Data Scientists, Wissenschaftler |
| Ausführbarer Code | Rust (via Playground) | Python, R, Julia (via Jupyter Kernel) |
| Inhaltsformat | Markdown | Markdown + Jupyter Notebooks (.ipynb) |
| Interaktivität | Editable Codeblöcke | Vollständig ausführbare Notebooks |
| Setup-Komplexität | Gering | Höher (Python + Jupyter erforderlich) |
| Ausgabeformate | HTML | HTML, PDF, LaTeX |
| Einsatzgebiet | Software-Dokumentation | Wissenschaftliche Publikationen |
Fazit des Vergleichs: mdBook eignet sich hervorragend für schlanke, entwicklerzentrierte Dokumentation. JupyterBook ist die bessere Wahl, wenn ausführbare Notebooks und wissenschaftliche Reproduzierbarkeit im Vordergrund stehen.
Zotero & Literaturverwaltung
Zotero ist ein freies Literaturverwaltungsprogramm das Quellen sammelt, organisiert und als BibTeX-Datei exportiert. In Kombination mit mdBook ermöglicht es automatische Literaturverzeichnisse und Inline-Zitationen. [2]