Neu in meinem Wiki: Werkzeuge für statische Dokumentationen

Manchmal, wenn man etwas angefangen hat, läßt es einem nicht mehr los. So ging es mir mit dem Beitrag »Software-Dokumentation mit Markdown«, den ich vorgestern hier im Blog Kritzelheft veröffentlicht hatte. In meinen Kommentaren bekam ich einen Hinweis auf zwei weitere, interessante Werkzeuge und über meinen Feedreader schneite ein drittes herein. Und so war ich gestern und heute fast den ganzen Tag damit beschäftigt, mir diese Teile genauer anzuschauen.

Markdoc

Da war erst einmal Markdoc, ein Markdown basiertes, freies (MIT-Lizenz) Werkzeug zur Erstellung statischer Dokumentationsseiten (nicht zu verwechseln mit der in Python geschriebenen, gleichnamigen Wiki-Software). Es ist eine JavaScript-Anwendung und gegenüber anderen, ähnlichen Tools habe ich auf den ersten Blick keine Besonderheiten entdeckt. Aber da man nie wissen kann, habe ich dem Teil dennoch eine Seite in meinem Wiki spendiert.

Docusaurus

Bedeutend interessanter ist da schon Docusaurus, ein Open-Source-Generator (MIT-Lizenz) für statische Websites, der ebenfalls Markdown-Dateien in eine Dokumentations-Website konvertiert. Docusaurus wurde von Facebook entwickelt und ist in Node.js geschrieben.

Tutorials

• Gabriel Afonso: Dokumentation mit Docusaurus, Ordix-Blog vom 18. März 2021
• Example Docusaurus site using GitLab Pages

Links

• Docusaurus Home
• Docusaurus @ GitHub
• Docusaurus im Markdown Guide

Die App geht mit ihren Möglichkeiten schon ein wenig über MkDocs hinaus (sie besitzt so etwas wie eine eingebaute Template-Sprache), ist aber eben kein Python, sondern JavaScript. Daher sehe ich auch hier für mich keinen Anreiz für einen Umstieg. Aber sie ist sicher für den einen oder anderen von Euch da draußen interessant. Daher gibt es auch dafür eine Seite in meinem Wiki.

Quarto

Am längsten beschäftigt hat mich Quarto, ein wissenschaftlich-technisches Open-Source-Veröffentlichungssystem, das auf Pandoc aufbaut. Es ermöglicht die nahtlose Integration von Text und Code in Publikationsqualität. Quarto ist ein Werkzeug, das ähnlich wie der Org-mode des Emacs für reproducible Research entwickelt wurde und unterstützt dabei die Programmiersprachen Python, R und Observable (ein JavaScript-Framework für Datenanalyse – kannte ich bis gestern auch noch nicht). Quarto kann aus Jupyter-Notebooks und aus RStudio heraus, aber eben auch aus jedem stinknormalen Texteditor genutzt werden (ich habe das mit TextMate und Geany getestet).

Literatur

• Lloyd Hamilton: Markdown just got a facelift. Hello Quarto, Medium.com vom 30. Mai 2022
• Charles Teague: Positioning Content in the Margin. Create ‘Tufte’ style documents with sidenotes, margin tables and figures, and other margin content, Quarto Blog vom 17. Februar 2022
• Tony Hirst: A Quick Look at the Quarto Pandoc Publishing System and Visual Markdown Editor, OUseful.Info vom 7. September 2021

Videos

Tutorials

• Quarto Tutorials
• Quarto Guide
• Quarto Reference
• Quarto Gallery

Links

• Quarto Home
• Quarto @ GitHub
• Quarto Blog

Quarto klingt hochinteressant und hat mich am längsten beschäftigt. Und das nicht nur, weil ich dafür gestern eine komplette LaTeX-Neuinstallation vornehmen mußte, sondern vor allem, weil Quarto ein komplexes Framework mit nahezu unbegrenzten Möglichkeiten ist. Es ist sicher kein System, mit dem man so nebenher auf die Schnelle ein paar Webseiten heraushaut, aber wenn man anspruchsvolle Projekte verwirklichen will, kann Quarto das Werkzeug der Wahl sein.

Ich werde Quarto sicher noch ausführlicher testen und darüber berichten. Aber zuerst einmal hat auch dieses Werkzeug eine Heimat in meinem Wiki gefunden.

---

(Kommentieren)