Worknote: Software-Dokumentation mit Markdown

Für die Dokumentation meiner Software-Projekte verwende ich seit etlichen Jahren Markdown mit MkDocs als Framework, um statische (HTML5)-Seiten herauszuschreiben. Ich habe – wie regelmäßige Leser des Schockwellenreiters wissen – sowohl mit Sphinx als auch mit AsciiDoc experimentiert, aber MkDocs gefiel mir einfach besser. Das größte Projekt, das ich damit durchgezogen habe, sind meine Seiten zu Processing.py, die Ihr unter dem Titel »Processing.py in Beispielen« im Netz finden könnt.

MkDocs bildet zusammen mit dem Read the Docs Sphinx Theme und den Python Markdown Extensions eine einfache, schnelle und komfortable Möglichkeit, meine Texte als statische HTML-Seiten herauszuschreiben – aber eben nur als Webseiten. Das Erzeugen von PDFs und oder Ebooks ist nur mit Klimmzügen und über dem Umweg über Pandoc möglich. Und da zum Beispiel Pandoc MathJax-Ausdrücke anders behandelt als MkDocs ist bei Texten, in denen mathematische Formeln zu finden sind, Handarbeit angesagt.

Genau das will HonKit vermeiden. HonKit ist ein freies (Apache-2.0-Lizenz) JavaScript-Werkzeug, um Bücher mit Markdown oder AsciiDoc zu bauen. HonKit kann die Inhalte sowohl als HTML-Seiten wie eben auch als Ebook (PDF, ePub oder Mobi) ausgeben, ohne daß man in den Markdown-Quellen noch einmal herumfummeln muß.

HonKit ist eine (freundliche) Fork von GitBook (Legacy), das nicht mehr weiterentwickelt wird.

Flavio Copes hat vor ein paar Tagen in »How to create ebooks with Markdown« über seine Erfahrungen mit HonKit berichtet und er ist ziemlich begeistert. Aber auch von MkDocs gibt es mit »Build Your Python Project Documentation With MkDocs« ein erst wenige Tage altes und ausführliches Tutorial von Martin Breuss.

Ich bin hin- und hergerissen. Für MkDocs spricht, daß ich damit schon etliche Jahre Erfahrung habe und daß es in Python geschrieben ist, der Programmierumgebung, in der ich mich zu Hause fühle. Für HonKit spricht, daß es eben nicht nur Webseiten, sondern auch Ebooks und gedruckte Bücher aus einer Quelldatei erstellen kann.

Auf jeden Fall sollte ich Honkit einmal testen. Ich habe dem Teil daher – wie immer in solchen Fällen – erst einmal eine Seite in meinem Wiki spendiert.

War sonst noch was? Ach ja, GamesFromScratch machte mich auf VSCodium aufmerksam, einem Visual Studio Code ohne Microsoft. Ist in Zeiten, in denen Microsoft den Atom-Editor gekillt hat, vielleicht keine schlechte Alternative gegenüber Microsofts Zwang zu Monokulturen.

---

4 Kommentare

---

Für etwas mehr Qual bei der Wahl: https://docusaurus.io (facebook) und https://markdoc.io (markdown extended.

– Erwin L. via Email (Kommentieren) (#)

---

VS Codium hab ich die letzten Monate ausprobiert, kann mich der Empfehlung anschließen. Verhält sich wie VS Code, ohne dass mir etwas störendes aufgefallen ist

– Herr R. via Twitter (Kommentieren) (#)

---

One more thing… Plenti, ein Open Source Static Site Generator SSG (Svelte) https://plenti.co/.
Eine weitere Single Page Application SPA (lädt die Struktur, danach bloss die Daten-Differenz) - das ist vielleicht das Besondere… s. https://plenti.co/docs/build in der Doc 😉

– Erwin L. via Email (Kommentieren) (#)

---

Lieber Jörg, da Dich das ja gegenwärtig interessiert … .-) Vielleicht auch das ? https://jamstack.org/generators/

– Karl-Heinz B. via Email (Kommentieren) (#)

---

(Kommentieren)