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:

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.

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]

Tutorial

Voraussetzungen

Für mdBook müssen Rust und Cargo installiert sein: https://rust-lang.org/tools/install/

Überprüfen der Installation:

rustc --version
cargo --version

mdBook installieren

Cargo ist der Paketmanager von Rust und wird zur Installation von mdBook verwendet:

cargo install mdbook

Überprüfen der Installation:

mdbook --version

Erstes Projekt erstellen

Ein neues mdBook-Projekt erzeugen:

mdbook init seminar-mdbook

In das Projektverzeichnis wechseln:

cd seminar-mdbook

Projektstruktur

seminar-mdbook/
    book/
    src/
        SUMMARY.md
        chapter_1.md
    book.toml

Lokalen Entwicklungsserver starten

Der Entwicklungsserver ist über Localhost erreichbar und ermöglicht Live Reload bei Dateiänderungen.

mdbook serve --open

Die Dokumentation ist anschließend unter:

http://localhost:3000

erreichbar. Änderungen an Markdown-Dateien werden automatisch erkannt und der Browser aktualisiert sich ohne manuellen Reload.

Dokumentation bauen

Zum Generieren der fertigen HTML-Ausgabe:

mdbook build

Die Ausgabe landet im book/-Verzeichnis und kann direkt auf einem Webserver deployed werden. Das Deploy der statischen HTML-Ausgabe auf einen Webserver ist damit ohne weitere Konfiguration möglich.

Wichtige Dateien

Die Datei SUMMARY.md definiert die Navigation und Kapitelstruktur des Buchs. Die Datei book.toml ist die Konfigurationsdatei des Projekts und steuert Titel, Autoren und Plugins.

Mermaid-Einbindung

Installation

cargo install mdbook-mermaid

mdbook-mermaid install

Anschließend in die book.toml einbinden.

Zotero & Literaturverwaltung

Voraussetzungen

• Zotero installiert und Quellen gesammelt [2]
• mdBook-Projekt vorhanden

Installation

Das Plugin mdbook-bibtex wird über Cargo installiert:

cargo install mdbook-bibtex

Konfiguration in book.toml

Anschließend wird das Plugin in der book.toml konfiguriert: [3]

[preprocessor.bibtex]
bibliography = "src/zotero_seminar/zotero_seminar.bib"
title = "Literaturverzeichnis"
style = "ieee"

Bibliothek aus Zotero exportieren

1. Zotero öffnen
2. Sammlung rechtsklick -> Exportieren
3. Format BibTeX wählen
4. Datei speichern unter src/zotero_seminar/zotero_seminar.bib

Zitieren im Text

Zitationen werden direkt im Markdown eingebunden:

mdBook ist ein Static Site Generator. <a href="literaturverzeichnis.md#noauthor_installation_nodate"><abbr title="“Installation - mdBook Documentation.” Accessed: June 18, 2026. [Online]. Available: https://rust-lang.github.io/mdBook/guide/installation.html">[1]</abbr></a>

Der Zitierschlüssel entspricht dem Schlüssel in der .bib-Datei. Das Literaturverzeichnis wird von mdbook-bibtex automatisch am Ende des Buchs generiert.

Ergebnis

Beim Build erzeugt mdbook-bibtex automatisch:

• Inline-Zitationen im gewählten Stil (hier: IEEE)
• Ein vollständiges Literaturverzeichnis am Ende des Buchs

How-To

Rust-Codebeispiel einbinden

mdBook unterstützt ausführbare und testbare Rust-Codeblöcke direkt in Markdown. Ein Codeblock kann dabei entweder nur zur Anzeige dienen oder direkt im Rust Playground ausgeführt werden.

Beispiel: Einfache mathematische Funktionen

main.rs definiert zwei Funktionen:

fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

fn main() {
    println!("2 + 3 = {}", add(2, 3));
    println!("5 - 2 = {}", subtract(5, 2));
}

Ausgabe im Browser:

2 + 3 = 5
5 - 2 = 3

Funktionsreferenz

Ausführbare Codeblöcke

Das Attribut Editable macht einen Codeblock im Browser direkt bearbeitbar:

fn add(a: i32, b: i32) -> i32 {
    a + b
}

fn main() {
    println!("2 + 3 = {}", add(2, 3));
}

Rust-Doctests

Ein Doctest ist ein automatisch testbarer Codeblock direkt in der Dokumentation. Mit mdbook test werden alle Rust-Codeblöcke automatisch getestet:

mdbook test

Mermaid-Diagramm

Das folgende Klassendiagramm zeigt die Struktur eines einfachen Fußballspiels in Rust, durch Mermaid modeliert. Es beschreibt die beteiligten Klassen, ihre Attribute und Methoden sowie die Beziehungen zwischen ihnen. [4]

---
config:
  layout: elk
  elk:
    direction: RIGHT
---
classDiagram
    class Game {
      +Team team_a
      +Team team_b
      +Ball ball
      +start()
      +score_goal(team: Team)
    }

    class Team {
      +String name
      +Player[4] players
      +u8 score
      +add_goal()
    }

    class Player {
      +String name
      +Position position
      +kick(ball: Ball)
    }

    class Ball {
      +f32 x
      +f32 y
      +move(direction: Direction)
    }

    class Position {
      <<enumeration>>
      GOALKEEPER
      DEFENSE
      MIDFIELD
      ATTACK
    }

    class Direction {
      <<enumeration>>
      UP
      DOWN
      LEFT
      RIGHT
    }

    Game --> Team : has
    Game --> Ball : uses
    Team --> Player : includes
    Player --> Ball : interacts with
    Player --> Position : uses
    Ball --> Direction : moves in

Das Spiel (Game) verwaltet zwei Teams und einen Ball. Jedes Team besteht aus vier Spielern, die jeweils eine Position (Goalkeeper, Defense, Midfield oder Attack) einnehmen. Ein Spieler kann den Ball treten, der sich dann in eine der vier Richtungen (Direction) bewegt.

Reference

Diese Referenz dokumentiert die technischen Bestandteile von mdBook. Sie dient als Nachschlagewerk für Dateien, Befehle und Konfigurationsoptionen.

Projektstruktur

CLI-Befehle

book.toml

[book]

[output.html]

SUMMARY.md

Beispiel

# Summary

- [Einleitung](README.md)
- [Kapitel 1](chapter_1.md)
  - [Unterkapitel](subchapter.md)

Markdown-Funktionen

Typischer Entwicklungs-Workflow

1. mdbook serve --open starten
2. Markdown-Dateien in src/ bearbeiten
3. Änderungen im Browser live prüfen
4. Mit mdbook build finale HTML-Ausgabe erzeugen

Häufige Optionen

Ausgabeformate

Zotero Konfiguration book.toml

Weiterführende Links

• Offizielle Dokumentation: https://rust-lang.github.io/mdBook/
• Rust Book (als mdBook): https://doc.rust-lang.org/book/
• Repository: https://github.com/rust-lang/mdBook
• JupyterBook: https://jupyterbook.org/

Glossar

mdBook

Tool zur Erstellung von Dokumentations-Webseiten aus Markdown-Dateien, entwickelt in Rust.

Markdown

Leichtgewichtige Auszeichnungssprache, die einfachen Text in HTML umwandelt.

Rust

Systemprogrammiersprache mit Fokus auf Sicherheit und Performance.

Statische HTML-Webseite

Webseite, die nur aus fixen HTML-Dateien besteht und keine serverseitige Verarbeitung benötigt.

Cargo

Paketmanager und Build-Tool von Rust, wird zur Installation von mdBook verwendet.

SUMMARY.md

Zentrale Datei eines mdBook-Projekts, die Navigation und Kapitelstruktur definiert.

book.toml

Konfigurationsdatei eines mdBook-Projekts, steuert Titel, Autoren und Plugins.

Localhost

Lokale Netzwerkadresse (http://localhost:3000) über die der mdBook-Entwicklungsserver erreichbar ist.

Deploy

Veröffentlichung der fertigen statischen HTML-Ausgabe auf einem Webserver.

Live Reload

Automatische Aktualisierung des Browsers wenn Markdown-Dateien geändert werden, ohne manuellen Reload.

Codeblock

Abschnitt in Markdown der Code darstellt, in mdBook können Rust-Codeblöcke direkt im Browser ausgeführt werden.

Rust Playground

Browser-basierte Umgebung zum Ausführen von Rust-Code, in mdBook über den Play-Button erreichbar.

Doctest

Automatisch testbarer Codeblock direkt in der Dokumentation, ausführbar mit mdbook test.

Editable

Attribut für Rust-Codeblöcke das dem Leser erlaubt den Code direkt im Browser zu bearbeiten.

Mermaid

Diagramm-Werkzeug das Diagramme aus Textbeschreibungen generiert, in mdBook über das mdbook-mermaid Plugin eingebunden.

BibTeX

Format zur Verwaltung und Speicherung von Literaturquellen, das vor allem im LaTeX-Umfeld verwendet wird.

JupyterBook

Dokumentationstool für Data Scientists und Wissenschaftler, unterstützt ausführbare Jupyter Notebooks.

Jupyter Notebook

Interaktives Dokument das Code, Text und Ausgaben kombiniert, unterstützt Python, R und Julia.

Static Site Generator

Tool das aus Quelldateien wie Markdown fertige statische HTML-Webseiten generiert.

Diátaxis

Framework zur Strukturierung von Dokumentation in vier Typen: Tutorial, How-to Guide, Explanation und Reference.

Impressum

Datenschutzerklärung

1. Datenschutz auf einen Blick

Diese Datenschutzerklärung klärt dich über die Art, den Umfang und Zweck der Verarbeitung von personenbezogenen Daten innerhalb dieses Onlineangebotes auf. Da ich diese Website als Privatperson betreibe und großen Wert auf Datenschutz lege, werden hier so wenig Daten wie möglich erfasst. Es gibt kein Tracking, keine Werbe-Cookies und keine Analyse-Tools.

2. Verantwortlicher

Verantwortlich für die Datenverarbeitung auf dieser Website im Sinne der Datenschutz-Grundverordnung (DSGVO) ist:

3. Datenerfassung auf dieser Website (Server-Log-Dateien)

Ich hoste diese Website selbst auf einer privaten Server-Infrastruktur unter Einsatz von Docker und Nginx Proxy Manager. Um die Seite sicher und fehlerfrei zur Verfügung stellen zu können, werden bei jedem Aufruf der Website automatisch Informationen erfasst und in sogenannten Server-Log-Dateien (Access Logs) gespeichert. Das sind technische Daten, die dein Browser automatisch übermittelt:

• Besuchte Seite auf unserer Domain
• Datum und Uhrzeit der Serveranfrage
• Browsertyp und Browserversion
• Verwendetes Betriebssystem
• Referrer URL (die zuvor besuchte Seite)
• Hostname des zugreifenden Rechners
• IP-Adresse

Eine Zusammenführung dieser Daten mit anderen Datenquellen wird nicht vorgenommen. Die Erfassung dieser Daten erfolgt auf Grundlage von Art. 6 Abs. 1 lit. f DSGVO. Ich habe ein berechtigtes Interesse an der technisch fehlerfreien Darstellung, der Sicherheit und der Optimierung meiner Website – hierzu müssen die Server-Log-Dateien temporär erfasst werden.

4. Kontakt per E-Mail

Wenn du mir über die angegebene E-Mail-Adresse eine Nachricht schickst, werden deine E-Mail-Adresse und der Inhalt deiner Mail gespeichert, damit ich deine Anfrage bearbeiten und beantworten kann. Diese Daten gebe ich nicht ohne deine Einwilligung weiter. Die Verarbeitung dieser Daten erfolgt auf Grundlage von Art. 6 Abs. 1 lit. f DSGVO (berechtigtes Interesse an der Bearbeitung von Anfragen). Ich lösche die Anfragen, sofern diese nicht mehr erforderlich sind und keine gesetzlichen Aufbewahrungspflichten bestehen.

5. Lokaler Speicher (Local Storage) statt Cookies

Diese Website wird als statische Seite betrieben und setzt keine Tracking-, Werbe- oder Analyse-Cookies.

Um dir jedoch eine angenehme Nutzung zu ermöglichen, speichert die Website deine Anzeigeeinstellungen lokal in deinem Browser (sogenannter Web Storage / Local Storage). Dazu gehört beispielsweise das von dir gewählte Farb-Theme (z.B. Light- oder Dark-Mode) sowie der Status der Seitenleiste (auf- oder zugeklappt). Diese Daten werden nicht an den Server übertragen, verbleiben ausschließlich auf deinem Endgerät und dienen rein der technischen Funktionalität und Bedienbarkeit der Website.

6. Deine Rechte

Du hast jederzeit das Recht, unentgeltlich Auskunft über Herkunft, Empfänger und Zweck deiner gespeicherten personenbezogenen Daten zu erhalten. Du hast außerdem ein Recht, die Berichtigung oder Löschung dieser Daten zu verlangen. Wenn du eine Einwilligung zur Datenverarbeitung erteilt hast, kannst du diese jederzeit für die Zukunft widerrufen. Außerdem steht dir ein Beschwerderecht bei der zuständigen Aufsichtsbehörde zu.

Literaturverzeichnis