mdBook - Ein Kommandozeilen-Tool zum Erstellen von Büchern mit Markdown

 (rust-lang.github.io)
4 Punkte von GN⁺ 2023-07-01 | 1 Kommentare | Auf WhatsApp teilen
  • Wenn Dokumentation und Tutorials in Buchform veröffentlicht werden sollen, bietet mdBook 0.5.3 sowohl Markdown-basiertes Schreiben als auch gut durchsuchbare Ausgabe
  • Dank der leichtgewichtigen Markdown-Syntax und der integrierten Suche können sich Autorinnen und Autoren stärker auf Inhalte als auf Formatierung konzentrieren
  • Mit Syntax-Highlighting für Codeblöcke und Theme-Dateien lassen sich die für technische Dokumentation nötige Lesbarkeit und das Ausgabeformat anpassen
  • Preprocessors und Backends dienen als Erweiterungspunkte für benutzerdefinierte Syntax, Inhaltsanpassungen und das Rendern in mehrere Ausgabeformate
  • Da es im Rust-Projekt und für das Buch The Rust Programming Language verwendet wird, ist die Anbindung an das Rust-Dokumentations-Ökosystem groß

Grundfunktionen für die Erstellung von Markdown-Büchern

  • mdBook ist ein Kommandozeilen-Tool zum Erstellen von Büchern mit Markdown
  • Es eignet sich für die Erstellung sauber strukturierter und leicht navigierbarer Inhalte wie Produktdokumentation, API-Dokumentation, Tutorials und Kursmaterialien
  • Es bietet zugleich Funktionen, die das Schreiben und Lesen unterstützen
    • Konzentration auf Inhalte durch die leichtgewichtige Markdown-Syntax
    • Integrierte Suche innerhalb des Buchs
    • Farbiges Syntax-Highlighting für Codeblöcke in mehreren Sprachen
    • Anpassbares Ausgabeformat über Theme-Dateien

Erweiterbarkeit und Verbindung zum Rust-Ökosystem

  • Preprocessors können für benutzerdefinierte Syntaxerweiterungen und Inhaltsanpassungen zuständig sein
  • Über Backends ist das Rendern in mehrere Ausgabeformate möglich
  • mdBook ist für Geschwindigkeit, Sicherheit und Einfachheit in Rust geschrieben
  • Es unterstützt automatische Tests für Rust-Codebeispiele

Praktische Einsatzfälle und Möglichkeiten zur Mitwirkung

  • Die mdBook-Dokumentation selbst ist ein Beispiel für ein mit mdBook erzeugtes Ergebnis
  • Das Rust-Programmiersprachenprojekt verwendet mdBook, und auch das Buch The Rust Programming Language ist ein Anwendungsfall
  • mdBook ist ein kostenloses Open-Source-Projekt
  • Der mdBook-Quellcode und die Dokumentation werden unter der Mozilla Public License v2.0 veröffentlicht

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2023-07-01
Hacker-News-Kommentare

  • Soweit ich mich erinnere, nutzt diese Plattform CDN-gehostete Bibliotheken, statt Bibliotheken zu bündeln oder zu vendoren. Dadurch sind Nutzer nicht nur CDN-Ausfällen ausgesetzt, sondern auch den Daten, die der jeweilige Server sammelt
    Noch bedauerlicher ist, dass die Art, wie im Frontend Highlight.js und MathJax verwendet werden, sehr verschwenderisch ist. Jeder Client muss Syntax und LaTeX selbst parsen und rendern und bei jedem Besuch dieselbe Arbeit wiederholen, um zum gleichen Ergebnis zu kommen. Syntax-Highlighting könnte zur Build-Zeit verarbeitet werden, und es gibt kaum einen Grund, dafür JavaScript zu benötigen

    • MathJax scheint über ein CDN gehostet zu werden, während CSS und andere JS-Dateien direkt neben der HTML-Datei liegen
      Vermutlich hat man sich dafür entschieden, weil die MathJax-Unterstützung optional ist: https://rust-lang.github.io/mdBook/format/mathjax.html
      Allerdings lädt das MathJax-JS wahrscheinlich wiederum zusätzliche Dateien vom CDN nach, daher ist schwer nachzuvollziehen, warum nicht die gesamte MathJax-Datei neben dem erzeugten HTML abgelegt wird
    • Dazu scheint es bereits einen offenen PR zu geben: https://github.com/rust-lang/mdBook/pull/1918

  • In diesem Thread wurden als Doku- und Static-Site-Tools unter anderem Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook genannt
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • Ich habe auch schon nimibook verwendet
      Es ist ein Port von mdBook nach Nim, erweitert aber auch die Funktion, mit Nims JavaScript-Backend interaktive Inhalte zu erzeugen. Ich habe es selbst noch nicht verwendet, aber mir gefällt die Idee, bei Bedarf interaktive Elemente an einer Stelle erstellen zu können: https://pietroppeter.github.io/nimib/interactivity.html
    • Auch Sphinx sollte man kaum auslassen. Der Workflow passt besser zu einem Buchformat als zu Blog-, Forum- oder Thread-Formaten
    • HackMD ist oft meine erste Wahl, wenn ich Markdown-Dokumente mit Formelnotation erstellen will, die sich teilen und gemeinsam bearbeiten lassen: https://hackmd.io/
    • Es wäre schön, wenn es eine Vergleichstabelle oder Website zu den Funktionen solcher Tools gäbe. Ich würde gern integrierte Suche, PDF-Ausgabe, ePub-Ausgabe, mehrere Themes und andere Funktionen vergleichen
    • https://jupyterbook.org/en/stable/ gibt es auch. Ich arbeite an Jupyter Book mit

  • Ich habe MdBook, Jekyll und MkDocs ausprobiert; MdBook wirkte beim Standardprojekt zwar glatt, aber auch zu minimalistisch. Beim Blick in den Quellcode von MdBook-Seiten, die mir gefielen, stellte sich heraus, dass sie teils mit benutzerdefiniertem Rust-Code erweitert waren
    Meine Empfehlung wäre: MkDocs als vernünftig flexible Standardwahl, Jekyll, wenn man mehr Flexibilität braucht, etwa für Landingpages oder Blogs, und Antora, wenn man die bestmögliche Doku-Website aus mehreren Projekten und mehreren Versionen bauen will und bereit ist, viel Aufwand zu investieren. AsciiDoc hat viele nützliche Funktionen fürs Schreiben von Dokumentation
    Hugo wirkt wie Jekyll flexibel, verlangt aber mehr Aufwand, bis es sich so anpassen lässt, wie man es möchte, und die Unterschiede im Verhalten zwischen den Themes scheinen zu groß zu sein. Einem von mir genutzten Theme fehlte eine benötigte Funktion, ich wollte deshalb auf ein anderes wechseln, aber der Umstieg war nicht einfach, also habe ich am Ende aufgegeben. MdBook wirkt ziemlich aktiv und wird wohl am Ende aufholen

    • Ich bin langjähriger Jekyll-Nutzer und finde es für Blogs immer noch hervorragend, aber unter den Static-Site-Generatoren für Dokumentationsseiten fand ich Docusaurus am besten: https://docusaurus.io/
      Ich habe es lange hinausgezögert, weil ich keine JavaScript-basierten Tools verwenden wollte, aber als ich es ausprobierte, war der Einstieg leicht, es war sehr schnell, die Standardseite sah großartig aus und ließ sich einfach anpassen. Auch die MDX-Unterstützung ist hervorragend
    • Die Landingpage des material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) ist wirklich elegant. Das ist besonders beeindruckend, wenn man bedenkt, dass es sich um ein Theme für Standardsoftware handelt
    • Für Wissenschaft und Statistik halte ich Quarto für hervorragend: https://quarto.org
    • Von Antora hatte ich bisher noch nicht gehört, aber die Art, wie es Dokumentation aus mehreren Repositories zusammensetzt und Versionen über Branches verwaltet, entspricht genau dem, was ich möchte. Schade ist nur, dass kein MDX verwendet wird, obwohl meine bestehende Dokumentation eine Kombination aus Markdown und interaktiven React-Komponenten ist
    • Ich nutze MkDocs viel und mag es sehr
      Ich probiere auch BookStack aus; das ist eher wikiartig, aber gut für Leute, die nicht so technikaffin sind. MkDocs-Projekte bearbeite ich normalerweise in VSCode und speichere sie in einem Git-Repository, während bei BookStack alles webbasiert ist

  • Früher habe ich die Generierung von til.secretGeek.net mit GitBook gemacht, aber mit der Zeit wurde es immer langsamer, sodass ein Site-Build 45 Minuten dauerte, und Funktionen, die ich nutzte, wurden eingestellt oder zu „premium“. Im Grunde war das der Beginn der Enshittification
    Wenn man ein kostenloses Tool nutzt, das zu gut aussieht, um wahr zu sein, ist die Wahrscheinlichkeit groß, dass es in ein paar Jahren kaputtgemacht wird. Ich habe am Ende selbst einen sehr minimalistischen Static-Site-Generator in .NET geschrieben, sodass die Builds wieder in wenigen Sekunden durchlaufen. Ich bewerbe ihn aber nicht zur Nutzung durch andere, weil ich ihn bei Popularität wahrscheinlich am Ende genauso kaputtmachen würde

  • Ich habe mdBook in mehreren Projekten verwendet, aber inzwischen fühlt sich material for mkdocs angenehmer an, weil es deutlich mehr Funktionen mitbringt
    Zum Beispiel gefällt mir das Seiteninhaltsverzeichnis rechts, und genau diese Funktion fehlt bei mdBook spürbar. Bei mdBook scheint es üblich zu sein, SUMMARY sehr detailliert zu strukturieren und Inhalte, die ursprünglich auf einer Seite stehen könnten, auf mehrere Dateien aufzuteilen

    • material for mkdocs ist gut genug, dass sich die Installation von Python und das Einrichten einer virtuellen Umgebung lohnen
    • Ich mag MkDocs schon ziemlich lange. Es erledigt die Arbeit mit minimalem Aufwand, es gibt viele brauchbare Themes, und eigene Anpassungen oder ein neues Theme zu erstellen ist vergleichsweise einfach
    • Ich verwende https://github.com/JorelAli/mdBook-pagetoc, um ein Inhaltsverzeichnis pro Kapitel zu bekommen

  • Vor ein paar Tagen habe ich angefangen, mdBook für die Dokumentation eines kleinen Projekts zu verwenden, und es ist genau der kleine Static-Site-Generator, den ich brauche
    Ich habe auch HUGO ausprobiert, aber im Vergleich zu mdBook wirkt es zu groß und aufgebläht. Im Moment bearbeite ich die Doku in Obsidian/VIM, pushe sie nach Gitea, und innerhalb einer Minute wird die öffentliche Dokumentation erzeugt

    • Ich verwende Hugo mit dem book theme(https://github.com/alex-shpak/hugo-book). Wenn man mit Hugo nicht vertraut ist, braucht man etwas Eingewöhnungszeit, aber danach gefällt einem die Flexibilität, die Hugo mit Shortcodes und Ähnlichem bietet
      Mit passenden Shortcodes kann man Bilder, Formeln usw. automatisch nummerieren. Ich frage mich, ob automatische Nummerierung auch in mdBook möglich ist. Es gibt außerdem ein Inhaltsverzeichnis rechts, Tags und die Möglichkeit, Seiten in Spalten aufzuteilen, und auch die KaTeX-Unterstützung ist gut. mdBook scheint MathJax zu verwenden, und die Bereitstellung ist einfach per push oder rsync möglich
    • Ich habe kürzlich angefangen, die PlantUML-Erweiterung zu verwenden, und sie hilft dabei, Architekturdiagramme in die Dokumentation einzubinden

  • Ich habe vor Kurzem angefangen, neuere Inhalte langsam von .md nach .mdx zu migrieren und mir das anzusehen, und es wirkte ziemlich erfrischend. Das Schwierigste an Markdown war für mich immer, dass jeder Dialekt andere Grenzen hat und auch die Art, diese Grenzen zu erweitern, völlig unterschiedlich ist.
    Mit 80–90 % des Standard-GitBook-Markdown-Dialekts bin ich sehr zufrieden, aber manchmal braucht man doch komplexe Tabellen, Code-Blöcke, bei denen nur ein paar Zeilen hervorgehoben werden und das Syntax-Highlighting erhalten bleibt, interaktive Slider, in Dokumente eingebettete Rechner oder bestimmte Graphen bzw. Diagramme. Ich weiß nicht, wie gut MDX in großen Teams funktionieren würde, aber für persönliche Projekte scheint es definitiv eine Verbesserung zu sein.

    • Ich habe zum ersten Mal von .mdx gehört und mir [0] angesehen. Offenbar habe ich die Standardisierungsentwicklung im Frontend nicht gut genug verfolgt.
      Es wäre schön, wenn die Dialekte verschwinden und es einen universellen Ansatz gäbe, aber in der Dokumentation steht: „MDX ist nicht an React gebunden und kann auch mit Preact, Vue, Emotion, Theme UI usw. verwendet werden und unterstützt sowohl die classic- als auch die automatic-JSX-Runtime.“ Es gibt auch bereits eine Svelte-Implementierung [1], daher bin ich nicht sicher, ob das nicht eher eine Büchse der Pandora ist, in der noch mehr an Frontend-Frameworks gebundene Dialekte entstehen. Auch innerhalb von .mdx könnte es zu Aufspaltungen kommen, und mit .md ist es womöglich ebenfalls nicht kompatibel.
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • Stimme ich voll zu. Als ich Mdsvex entdeckt habe, fühlte es sich lebensverändernd an: https://mdsvex.com
    • .mdx lässt sich sehr einfach mit https://astro.build/ verwenden. Astro ist ein JavaScript-Metaframework und verfolgt zugleich einen Static-Site-Generation-first-Ansatz, bei dem kein JS an den Client geschickt wird.
      Es gibt nutzbare Themes, aber für moderne Webentwickler dürfte es auch ziemlich einfach sein, selbst etwas zu bauen.

  • Ich habe das kostenlose Open-Source-Cross-Platform-Tool KeenWrite entwickelt, um Markdown-basierte Bücher zu erstellen: https://github.com/DaveJarvis/keenwrite
    KeenWrite ruft ConTeXt für den Dokumentsatz auf und verwendet im Vorschaumodus einen Fork von KeenType für den Formelsatz. PDFs lassen sich über die Kommandozeile erzeugen. Das Buch, an dem ich gerade arbeite, referenziert im Haupttext mehrere in externen Dateien definierte Variablen, übergibt PDF-Eigenschaften als Metadaten und kann mit dem Argument chapters nur ausgewählte Kapitel bauen. Das Verzeichnis theme enthält Satzanweisungen für Farben, Schriftarten, Layout, Anmerkungen usw.
    Beispielausgabe: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • Ich frage mich, warum Markdown oder ein ähnliches Format nicht das Standardformat für Bücher, Dokumentation und fast jede Art von Text ist. Seit ich vor ein paar Jahren zu Typora gewechselt bin, brauche ich für meine eigenen Texte kaum noch Word/Writer und nutze sie eigentlich nur noch, um Dokumente zu öffnen, die mir andere geschickt haben.
    Auch bei 90 % der Bücher, die ich lese, sehe ich keinen klaren Grund, warum sie nicht im Markdown-Format vorliegen sollten. Ich verstehe, dass man für schön gedruckte Papierbücher Satz braucht, aber bei den meisten Texten, die auf Computer oder Smartphone gelesen oder direkt aus MS/LibreOffice ausgedruckt werden, wird so ein Satz ohnehin nicht wirklich sauber gemacht.

    • Als Speicherformat ist Markdown ziemlich dürftig. Es gibt mit CommonMark einen halbwegs offiziellen Standard, aber der Funktionsumfang reicht nicht aus, weshalb die meisten auf andere Varianten wie GitHub Markdown setzen, und einzelne Apps erweitern Markdown oft auf untereinander inkompatible Weise.
      Es gibt bessere Alternativen wie AsciiDoc, aber die sind stärker auf Dokumentation spezialisiert und haben nicht annähernd den Schwung von Markdown. Wenn man bedenkt, dass Markdown ein relativ spät entstandenes Format ist, ist die bessere Frage vielleicht eher, warum Bücher überhaupt Markdown sein sollten. Gegenüber binären oder XML-basierten Formaten ist der größte Vorteil von Markdown, dass es als Klartext bis zu einem gewissen Grad lesbar ist, aber für die meisten Verlage und Leser ist das nicht besonders wichtig.
    • Beim Buchsatz gibt es viele Feinheiten und viel Komplexität, die für ungeübte Augen kaum sichtbar sind, und Markdown+CSS ist nicht ausgefeilt genug, um all das abzudecken. HTML/CSS+JS wäre technisch zwar möglich, liegt aber weit hinter dem aktuellen Stand des digitalen Satzes zurück.
      Das ist auch die klassische Ingenieursfalle „Das kann ich besser“, daher sollte man das nicht ohne Recherche einfach annehmen. Satz ist ein viel älteres Feld als die hier besprochenen Tools, und man sollte die wertvollen Einsichten und Techniken, die sich dort angesammelt haben, nicht nur deshalb verwerfen, weil Markdown für einige Zwecke fast ausreicht.
    • Ich schreibe beruflich viele Dokumente, und ich mag den Ansatz, Markdown und das gerenderte Ergebnis nebeneinander zu sehen. Wenn man sich an die Syntax gewöhnt hat, ist Markdown viel schneller als Editoren wie Word, und schon das Erstellen einer einzigen Liste in einem Texteditor wirkt umständlich.

  • mdBook ist einfach zu benutzen, und mir gefällt besonders, dass Benutzer ein Theme auswählen können. Ich verwende es hauptsächlich für die Online-Version von E-Books [0] und für kuratierte Materialien [1][2].
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/