{"id":672,"date":"2022-01-02T00:49:21","date_gmt":"2022-01-01T23:49:21","guid":{"rendered":"https:\/\/coffee21.de\/?p=672"},"modified":"2022-01-02T18:22:01","modified_gmt":"2022-01-02T17:22:01","slug":"markdown-und-mermaid","status":"publish","type":"post","link":"https:\/\/coffee21.de\/?p=672","title":{"rendered":"Markdown und Mermaid"},"content":{"rendered":"\n

Denken wir heute an ein Schreibprogramm kommt uns sofort Word<\/em> in den Sinn. Es ist sogar \u00fcblich das Wort Word<\/em> als Synonym f\u00fcr das Wort Schreibprogramm<\/em> zu verwenden. Ich finde das problematisch, weil Sprache eine Realit\u00e4t schafft, die schwer zu durchbrechen ist. Wir erschaffen damit eine Barriere die uns daran hindert den Blick zu weiten. Denn ist ein Schreibprogramm der Art von Word<\/em> oder LibreOffice Writer<\/em> immer sinnvoll? Es kommt eben auf den Einsatzzweck an. In diesem Artikel m\u00f6chte ich eine andere Herangehensweise vorstellen, welche auf Textdateien basiert und einige Vorteile mitbringt.<\/p>\n\n\n\n\n\n\n\n

Jeder hat sicherlich von dem Textsatzsystem TeX geh\u00f6rt, welches 1978 von dem herausragendem Informatiker Donald E. Knuth ver\u00f6ffentlicht wurde. Dieses Programm liest eine Textdatei ein und erzeugt daraus eine bin\u00e4re Dokumentdatei. Dies kann z. B. ein PDF-Dokument oder eine LibreOffice Writer Datei sein. Dieses Vorgehen hat den Vorteil, dass ich unabh\u00e4ngig bin von meiner bin\u00e4ren Dokument-Datei. Ich bin in der Lage aus der Textdatei jede beliebige Dokumentdatei zu erstellen. Die Textdatei ist sozusagen meine Quelldatei und diese ist sehr nachhaltig, weil ich diese mit Betriebssystem-Werkzeugen wie einem Texteditor auch nach 50 Jahren noch \u00f6ffnen und lesen kann. Au\u00dferdem kann ich eine Textdatei mit einem Versionsverwaltungssystem wie Git sehr gut versionieren und somit sehr einfach mit mehreren Personen an einem Dokument arbeiten. Zus\u00e4tzlich kann ich eine Textdatei \u00f6ffnen ohne zeitgleich eventuell darin enthaltenen Code auszuf\u00fchren. Textdateien haben viele Vorteile, aber Textdateien mit TeX-Auszeichnungen haben den Nachteil, dass sie f\u00fcr Menschen schwer lesbar sind. Aus diesem Grund haben sich Textsatzsysteme wie Markdown oder AsciiDoc entwickelt. Deren Ziel ist eine Textdatei, welche leicht lesbar und gut \u00fcberschaubar ist. Sie sind weniger m\u00e4chtig wie TeX, aber in vielen Anwendungsszenarien v\u00f6llig ausreichend.<\/p>\n\n\n\n

Markdown<\/a> wurde im Jahr 2004 von John Gruber und Aaron Swartz ver\u00f6ffentlicht. Das Ziel war eine vereinfachte und leicht lesbare Auszeichnungssprache zu erstellen. In der Praxis ist die Auszeichnung von Text leicht einpr\u00e4gbar und wird von vielen Texteditoren durch z.B. Syntax-Highlighting unterst\u00fctzt. Einen guten \u00dcberblick \u00fcber die Syntax liefert die Projektseite unter https:\/\/daringfireball.net\/projects\/markdown\/syntax<\/a>. Seinen Siegeszug begann Markdown genau wie AsciiDoc in der Softwareentwicklung zur Dokumentation von Programmen. Hier spielte es seine Vorteile der Versionierbarkeit mit Versionsverwaltungssystemen wie z.B. Git und des einfachen \u00f6ffnens und lesens einer Textdatei auf Serversystemen voll aus. Erst sp\u00e4ter kam Markdown beim Erstellen von B\u00fcchern am Anfang einer langen Prozesskette zum Einsatz. Hier kommt ein weiterer Vorteil von Textdateien zum Tragen. Textdateien lassen sich sehr gut mit Betriebssystemsoftware weiterverarbeiten, zusammenf\u00fcgen oder trennen. Ist die Syntax bekannt, l\u00e4sst sich sogar auf einzelne Felder wie z.B. der Titel oder die \u00dcberschriften zugreifen, die dann wiederum weiterverarbeitet werden k\u00f6nnen.<\/p>\n\n\n\n

Markdown wandelt Textdateien mit Markdown-Syntax in XHTML-Dateien um. Zum ersten Testen empfehle ich den Online-Editor Dillinger<\/a>. Auf der linken Seite steht der eigene Text in Markdown-Syntax und auf der rechten Seite aktualisiert sich permanent die Vorschau. Das fertige Dokument l\u00e4sst sich am Ende als Markdown-, PDF- oder HTML-Datei herunterladen.<\/p>\n\n\n\n

Pandoc<\/a> ist ein m\u00e4chtiger universeller Markup-Dokumentkonverter. Da Microsoft Word (docx) und LibreOffice (odt) auch nur in einem ZIP-Archiv verpackte Markup-Dateien sind, ist es mit Pandoc m\u00f6glich diese Art von Dateien in Markdown, AsciiDoc oder LaTeX umzuwandeln und zur\u00fcck. Aber auch PDF-Dokumente lassen sich generieren (nur in diese eine Richtung). Folgendes Kommando wandelt eine Textdatei mit Markdown-Syntax in eine PDF-Datei um:<\/p>\n\n\n\n

pandoc -s quelldatei.md -o zieldatei.pdf<\/code><\/pre>\n\n\n\n
Pandoc bedient sich daf\u00fcr im Hintergrund der Programme pdflatex<\/code>, lualatex<\/code>, xelatex<\/code>, latexmk<\/code>, tectonic<\/code>, wkhtmltopdf<\/code>, weasyprint<\/code>, prince<\/code>, context<\/code> oder pdfroff<\/code>. Auf meinem System, einem openSUSE Tumbleweed, verwendete pandoc pdflatex<\/code>.<\/p>\n\n\n\n
Einen \u00e4hnlichen Ansatz wie Markdown verfolgt das Werkzeug Mermaid<\/a>. Nur eben nicht f\u00fcr Textdokumente, sondern f\u00fcr Diagramme, Charts und Grafen. Das Projekt bietet ebenfalls einen Online-Editor<\/a> an. Auch hier ist auf der linken Seite der Quellcode und auf der rechten Seite die Vorschau angeordnet. Kleiner Tipp: In der ersten Zeile des Online-Editors steht das TD<\/em> f\u00fcr die Aufbaurichtung des Diagramms. Im Beispiel also Top-Down<\/em>. Es gibt noch LR<\/em> f\u00fcr Left-Right<\/em>.<\/p>\n\n\n\n
Ziel sollte es sein, den Mermaid-Sourcecode in ein Markdown-Dokument zu integrieren und daraus mit pandoc ein PDF-Dokument zu erstellen. Pandoc ben\u00f6tigt dazu einen Filter. Dieser l\u00e4sst sich wie folgt installieren:<\/p>\n\n\n\n
sudo npm -g install mermaid-filter <\/code><\/pre>\n\n\n\n
Im Markdown-Dokument k\u00f6nnte dann folgender Text enthalten sein:<\/p>\n\n\n\n
Beliebiger Text.\n\n```mermaid\ngraph LR\n   A(Markdown-Datei) -->|pandoc| B(PDF-Datei)\n```<\/code><\/pre>\n\n\n\n
Anschlie\u00dfend l\u00e4sst sich mit folgendem Befehl ein PDF-Dokument generieren:<\/p>\n\n\n\n
pandoc --variable papersize=a4paper \\\n       --variable lang=de \\\n       -F mermaid-filter \\\n       -s quelldatei.md \\\n       -o zieldatei.pdf<\/code><\/pre>\n\n\n\n
Das PDF-Dokument enth\u00e4lt jetzt den automatisch fertig gerenderten Grafen. Ein Vorteil, was andere vielleicht als Nachteil empfinden, ist, dass der Erstellende sich keine Gedanken um das Layout machen muss. Au\u00dferdem lassen sich \u00c4nderungen an dem Grafen mit sehr geringem Aufwand durchf\u00fchren.<\/p>\n\n\n\n
\"\"<\/a>
Generierte Grafik aus Mermaid-Code.<\/figcaption><\/figure><\/div>\n\n\n\n
Ziel war es einen kleinen Einstieg in Markdown zu geben und einen alternativen Weg bei der Dokumenterstellung darzustellen. Sehr empfehlen kann ich auch AsciiDoc<\/a> und nat\u00fcrlich LaTeX.<\/p>\n\n\n\n
\n\n\n\n
Dir hat der Artikel gefallen und\/oder Du m\u00f6chtest diesen Blog unterst\u00fctzen? Dann hinterlasse doch ein kleines Trinkgeld mit Bitcoin Lightning<\/a>! Der Autor freut sich dar\u00fcber. Als Dank kannst Du diesen Artikel als PDF-Datei herunterladen. <\/em><\/p>\n\n\n\n
Diese Paywall\/Schatztruhe befindet sich aktuell in der Entwicklung. Du bist gern eingeladen diese zu testen, aber ich \u00fcbernehme keine Verantwortung f\u00fcr eventuelle Sch\u00e4den bzw. Verluste. Der Quellcode befindet sich auf Github<\/a>. Dort kannst Du in einem Issue<\/a> gern Feedback oder Feature-W\u00fcnsche hinterlassen.<\/em><\/p>\n\n\n
[lnd chest amount=2500 memo=“coffee21.de 672″]<\/p>\n\n\n