Serie: Static Site Generators - mdBook

Hinweis: Dieser Artikel erscheint als Teil der Static Site Generators Serie und wurde von einem Mitglied der Community eingereicht – vielen Dank dafür!

Inhaltsverzeichnis

1. Einleitung
2. Hugo Teil 1
3. Publii
4. Hugo Teil 2
5. mdBook (das ist dieser Artikel)
6. Hugo Teil 3
7. Pandoc/Markdown

Viele Static-Site-Generatoren sind hervorragend geeignet, um z. B. Blogs, Landing-Pages, News-Seiten, Portfolio-Seiten etc. zu erstellen. Und es gibt z. B. für Hugo auch Themes, mit welchen man Dokumentationsseiten, Handbücher, Tutorials und Ähnliches erstellen kann.

Möchte man aber ausschließlich eine Dokumentation, ein Tutorial oder ein online lesbares Buch erstellen, gibt es auch noch andere, leichtgewichtigere Tools. Ich habe mich mit mdBook angefreundet, um solche Projekte zu verwirklichen.

Anlass, mir ein solches Tool zu suchen, war, dass ich die Aufgabe übernommen habe, die Dokumentation der Fediverse-Software Hubzilla komplett zu überarbeiten. Die alten Hilfedokumente waren rettungslos veraltet, oft unvollständig und insgesamt stellten sie ein ziemliches Chaos dar. Also habe ich für die Hubzilla-Association vor knapp einem Jahr damit begonnen, die Dokumentation in englischer und deutscher Sprache neu aufzubauen. Da die vorhandene Hilfe ein Chaos aus HTML-, Markdown-, bbCode- und Textdateien war und die Struktur auch eher "natürlich" (und damit chaotisch) entstanden, habe ich mir überlegt, wie und womit ich die Aufgabe angehen sollte. Der Vorteil bei der Hubzilla-Hilfe ist, dass die Hilfe als Hubzilla-Webseiten gerendert werden und man dadurch nicht auf ein bestimmtes Format festgelegt ist. Und weil ich bekennender Markdown-Fan bin, habe ich nach einer passenden Software gesucht, die mich auch beim strukturellen Aufbau unterstützt, ohne dass ich mich in endlosen Konfigurationen verlieren muss. Bei der Suche bin ich dann über mdBook gestolpert und habe damit recht schnell genau das richtige Tool gefunden.

mdBook ist in Rust geschrieben. Das hat auch einen guten Grund, denn es wurde für die Dokumentation dieser Programmiersprache entwickelt. Das Tool besteht aus genau einem Binary… und sonst nichts. Die Installation ist einfach. Entweder man lädt sich das passende Archiv aus dem Git-Repository herunter und entpackt die ausführbare Datei an die passende Stelle, oder man schaut, ob die Paketverwaltung der eigenen Distribution ein Paket bereithält.

mdBook verfügt nicht über ein GUI, sondern wird ausschließlich auf der Kommandozeile verwendet.

Um nun ein neues "Buch" zu erstellen, legt man ein Verzeichnis für das Projekt an und man beginnt mit einem simplen

mdbook init

Nun stellt einem mdBook noch zwei Fragen, nämlich, ob man automatisch ein .gitignore File erstellen möchte, welches verhindert, dass das erstellte Buch im Git-Repo aufgenommen wird...

Do you want a .gitignore to be created? (y/n)

...und es wird nach einem Titel für das Buch gefragt:

What title would you like to give the book?

Danach wird von mdBook der "Vollzug" gemeldet:

[INFO] (mdbook::book::init): Creating a new book with stub content

All done, no errors...

Man kann mdbook init auch mit einigen Parametern aufrufen. Der Parameter --theme sorgt dafür, dass das Standard-Theme in den Quellordner kopiert wird (so kann man das Theme nach den eigenen Vorstellungen anpassen). Der Parameter --force unterdrückt die Nachfragen nach dem Aufruf, --title legt den Titel des Buches schon beim Aufruf fest und --ignore ermöglicht die Auswahl, ob ein .gitirgnore erstellt werden soll.

Nach der Initialisierung liegt nun im Verzeichnis die folgende Datei- und Ordnerstruktur vor:

├── book ├── book.toml └── src ├── chapter_1.md └── SUMMARY.md

Das Verzeichnis book enthält nach dem Generieren der Webseite die komplette Struktur und alle erforderlichen Dateien, die man dann nur noch auf seinen Server hochladen muss.

Die eigentlichen Quelltexte muss man im Verzeichnis src erstellen. Die Datei chapter_1.md ist lediglich eine Beispieldatei für ein Kapitel und kann gelöscht werden. Essenziell hingegen ist die Datei SUMMARY.md.

Es handelt sich bei dieser Datei aber nicht um eine Zusammenfassung, wie der Dateiname suggeriert, sondern um das Inhaltsverzeichnis des zu erstellenden Buches.

Die Datei enthält den Titel "Summary" (Überschriftenebene 1) und darunter die Verweise auf die einzelnen Kapiteldateien (relativer Pfad zum src-Verzeichnis) als unsortierte Liste. Durch Erhöhung des Listeneinzugs kann man Unter- und Unterunterkapitel erstellen. Aus dieser Datei wird dann der Navigationsbereich (linke Seitenleiste) der Webseite erstellt.

Innerhalb des src-Verzeichnisses kann man weitere Unterordner erstellen, z.B. für einzubindende Dateien, wie Bilder etc.

Bei der Wahl der Dateinamen für die einzelnen Kapitel ist man frei. Sie müssen nur korrekt in SUMMARY.md⁣ verlinkt werden. Querverweise innerhalb der Kapitel-Dateien sind selbstverständlich auch möglich.

Eine weitere wichtige Datei ist die Datei book.toml. [1] Sie enthält die Konfiguration des Buches.

Nach der Initialisierung enthält sie lediglich den Abschnitt [book] mit den Schlüsselpaaren.

authors = [""]
language = "en"
src = "src"
title = ""

Der Autorenname (authors) ist leer, es sei denn, man verfügt bereits über eine Git-Konfiguration, in welche man den eigenen Namen eingegeben hat. In diesem Fall übernimmt mdBook diesen Autorennamen.

Die Sprache (language) ist zunächst auf Englisch (en) eingestellt. Hier kann man den gewünschten Ländercode angeben (z. B. de für Deutsch).

Unter src wird auf das Verzeichnis verwiesen, welches die Quelltexte enthält (Standard: src).

Schließlich findet man hier auch noch den Buchtitel (title), den man bei der Initialisierung eingegeben hat.

In der sehr guten Dokumentation zu mdBook (selbstverständlich mit mdBook erstellt) findet man die möglichen Konfigurations-Schlüsselpaare im Abschnitt 5.2 Configuration.

Hat man mit der Option --theme ein Themenverzeichnis erstellen lassen, kann man in diesem das Theme an die eigenen Bedürfnisse anpassen.

Sind nun die ersten Artikel / Kapitel geschrieben, kann man sich das Ergebnis vorab anschauen. Dafür ist bei mdBook ein einfacher Webserver eingebaut. Mit dem Kommando

mdbook serve --open

wird der Webserver gestartet, der Quelltext übersetzt und im Standard-Webbrowser (Option: --open) geöffnet. mdBook "beobachtet" außerdem den Quelltext und Änderungen daran werden sofort (also nach dem Speichern der entsprechenden Quell-Datei) im Webbrowser angezeigt.

Ist man zunächst zufrieden, kann man das Generieren der HTML-Dateien und der Ziel-Verzeichnisstruktur im Unterverzeichnis book mit dem Kommando

mdbook build

anstoßen.

Ist dies ohne Fehler durchgelaufen, kann nun der Inhalt des Verzeichnisses book auf den Server hochgeladen werden... das Buch ist online.

Bei der Anzeige der Seite findet man einige Icons für Einstellungen und zur Navigation. Die Seitenleiste mit dem Inhaltsverzeichnis kann man mittels des Hamburger-Icons ein- und wieder ausblenden.

Mit dem Pinsel-Icon kann man zwischen verschiedenen Standard-Themen (Farbschemata) wählen.

Man kann mit der book.toml ein Standard-Thema vorgeben, also z.B.

[output.html]
default-theme = "rust"

Das Lupen-Symbol ermöglicht eine Volltext-Suche im Buch.

Das Drucker-Symbol ermöglicht den Ausdruck des jeweiligen Beitrags.

mdBook ist ein einfaches, leicht zu bedienendes und schnelles System für die Erzeugung statischer Dokumentationsseiten. Was dabei herauskommt, kann man sich z.B. bei meiner Hubzilla KnowledgeDB anschauen: https://info.hubzilla.hu/. Den Quelltext dazu findet man hier: https://codeberg.org/derpepe/hz-knowledgedb.

Quellen:
[1] TOML : https://toml.io/en/
mdBook-Repositpry: https://github.com/rust-lang/mdBook
mdBook-Dokumentation: https://rust-lang.github.io/mdBook