Markdown und Co.

Seit Ende 2022 steht für mich fest, dass ich mit folgendem Workflow sehr gut zurecht komme:
Meine Texte schreibe ich in Markdown. Diese werden dann konvertiert und als HTML und PDF ausgegeben.

Eine effiziente Vorgehensweise ist es, das Schreiben der Inhalte von der endgültigen Formatierung zu trennen. Trotzdem sollen die Formatierungen schon im ASCII-Text (naja, Unicode-Text) erkennbar sein. Weitere Vorteile ergäben sich, wenn man eine Versionsverwaltung wie Git einsetzen würde, da diese zeilenweise Textdateien versioniert. Damit kann man z.B. bei einem Buch, das in einer Markdown-Datei geschrieben wird, jede Änderung nachvollziehen. Dies ist mit einem Textverarbeitungsprogramm (Word, Writer) so nicht möglich. Mein restlicher Workflow ist allerdings derzeit Cloud-basiert, so dass Git eine zusätzliche und für mich nicht vorteilhafte Verkomplizierung wäre.

Idee

Markdown ist bekanntlich eine vergleichsweise einfache Methode um sofort gut lesbaren strukturierten Text zu schreiben. Ohne Menüs, eine Maus oder Tastatur-Shortcuts zu nutzen kann man Texte mit hierarchischen Überschriften, Fett/Kursivschrift, Tabellen, Zitaten, Links, Fußnoten und Code-Fragmenten schreiben. Es sind bereits einige Bücher sowie viele E-Books in Markdown geschrieben worden.

Verschiedene Programme oder Libraries können Markdown in andere Formate konvertieren. Ich verwende das Tool pandoc, da es flexibel und sehr leistungsfähig ist. Das Zielformat für pandoc ist bei mir HTML. Darauf basiert dann z.B. meine Homepage.

HTML kann man wiederum heranziehen, um PDF-Dateien zu erzeugen. Dazu verwende ich Google-Chrome, da hier geeignete Kommandozeilenparameter zur Verfügung stehen.

Mein persönlicher Bedarf:

Ich verfasse für den Physik- und Informatikunterricht Skripte zu meinem Unterricht (primär für mich und als Tafelbild - kein Lehrwerk). Dabei werden die üblichen Features genutzt: Hierarchische Überschriften, Abbildungen, Einteilung in Spalten (meist für Beschreibungen neben Bildern), Mathematische Formeln (in TeX), Tabellen, Quelltexte (in unterschiedlichen "Sprachen"), Definitionen sowie Diagramme usw.

Außerdem habe ich mit dieser Technik diese Homepage neu gestaltet. Die Elemente Navigation, Inhaltsverzeichnis, Neueste Artikel sowie die Sitemap werden automatisch generiert, in dem die Markdowndateien sowie einzelne YAML-Dateien gelesen und verarbeitet werden.

Dies alles geht problemlos in Markdown mit den Erweiterungen von Pandoc und mir (s.u.).

Da die Funkübertragung an unsere digitalen Tafeln am ehesten mit iPads funktioniert, erzeuge ich zwei PDF-Ausgaben:

PDF-Dateien haben den Vorteil, dass alle Daten in einer Datei sind und diese final formatiert ist. Außerdem kann sie quasi jedes Gerät anzeigen, was bei eBooks so nicht gegeben ist.

Meine Ergänzungen

Ich habe einige Ergänzungen in CSS geschrieben bzw. in einem Python-Präprozessor programmiert. Beispiele:

Interpretieren: Quelltexte bestimmter Programmiersprachen werden ggf. ausgeführt, wenn sie mit “.execute” gekennzeichnet werden. Die Ausgaben werden in einem eigenen Kasten “Resultat” angehängt.

```{.java .execute}
System.out.println("Hello World");
```

wird zu:

System.out.println("Hello World");

Hello World

```mermaid
flowchart LR
    A[Idee] -->|Nachdenken| B(Planen)
    B --> C{Evaluieren}
    C -->|fragwürdig| D[Einstellen]
    C -->|realistisch| E((Durchführen))
    C -->|unausgegoren| B
```

Textboxen

gibt es in mehreren Farben als “fenced divs”, also eingerahmt in Doppelpunktfolgen:

::::{.m²_blue .m²_box}
#### Beispiel
Dazu kombinieren wir: 
`.m²_blue .m²_box` 
::::

Eine Überschrift Level 4 wird ansprechend angezeigt.

Beispiel

Dazu kombinieren wir: .m²_blue .m²_box

Praxis

Dienste wie z.B. Github zeigen Markdown-Dateien automatisch als gut aussehendes HTML an. Aber jeder kann selbst Tools einzusetzen, die optisch ansprechende Dokumente in vielen verschiedenen Formaten erzeugen können. Ich ziele derzeit nur auf HTML und daraus erzeugtes PDF (so werden beide mit CSS formatiert). [Man kann aber auch von Pandoc direkt PDF-, odt- oder epub-Dateien erzeugen lassen. Zu den Möglichkeiten siehe hier.]

Pandoc alleine erzeugt eine korrekte, aber nicht so hübsche HTML-Datei. Aber man kann mit der Kommandozeilenoption -H eine zusätzliche Datei in den Header der HTML-Datei einfügen lassen. Damit ist es einfach viele CSS-Styles einzubinden. Am Ende kann man mit -F eine weitere Datei als eine Art Fußzeile einfügen lassen. Dann gibt es noch den Befehl -``-toc, der ein Inhaltsverzeichnis generiert, das wiederum erst nach einer Formatierung mit obigen Styles wunschgemäß aussieht.

Chromium/Chrome kann über die Kommandozeile eine HTML-Datei direkt als PDF-Datei "ausdrucken". Dabei werden Formatierungsanweisungen der HTML-Datei beachtet, z.B. page-break-before, so dass man Kapitel oder Folien mit einer neuen Seite anfangen lassen kann. Man kann sogar das Aussehen der PDF-Datei komplett anders gestalten, da dabei @media print { ... } beachtet wird. Selbst Papiergrößen in CSS werden berücksichtigt.

Inzwischen werden bei mir mehrere Dateien inkludiert, die CSS-Zeilen regelmäßig ergänzt sowie der Aufruf von Pandoc und Chrome per Skript automatisiert. Deshalb habe ich mir ein Tool mdmachine.py geschrieben, das diese Aufgaben (und noch einiges mehr wie Navigationsspalte, sitemap usw.) erledigt. Neben diesem Tool wird benötigt:

Vorbemerkung

Idee

Mein persönlicher Bedarf:

Meine Ergänzungen

Beispiel

Praxis