2025-08-10
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 systemübergreifend 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.
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. Dies wird z.B. für Wikis, aber auch ganz gewöhnliche Texte genutzt. 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. diese Homepage.
HTML kann man wiederum heranziehen, um PDF-Dateien zu erzeugen. Dazu verwende ich Google-Chrome, da hier geeignete Kommandozeilenparameter zur Verfügung stehen.
flowchart LR
M -->PD --> H --> GC--> P
M@{ shape: doc, label: "Markdown
(single source
of truth)" }
PD@{ shape: lean-r, label: "Pandoc" }
H@{ shape: doc, label: "HTML" }
GC@{ shape: lean-r, label: "Google
Chrome" }
P@{ shape: doc, label: "PDF" }
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 LaTeX), Tabellen, Quelltexte (in unterschiedlichen "Sprachen"), Definitionen sowie Diagramme usw.
Außerdem habe ich mit dieser Technik diese Homepage neu angelegt. Beispielsweise werden die Elemente Navigation, Inhaltsverzeichnis, Neueste Artikel sowie die Sitemap von einem Pythonprogramm 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 in der Schule 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.
Ich habe einige Ergänzungen in CSS geschrieben bzw. in einem Python-Präprozessor programmiert. Beispiele:
```{.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
```
flowchart LR
A[Idee] -->|Nachdenken| B(Planen)
B --> C{Evaluieren}
C -->|fragwürdig| D[Einstellen]
C -->|realistisch| E((Durchführen))
C -->|unausgegoren| B
Mit diesem Text ist eine Marginalie verknüpft. Eine
Beispielmarginalie.
::::{.m²_blue .m²_box}
#### Beispiel
Dazu kombinieren wir:
`.m²_blue .m²_box`
::::Eine Überschrift Level 4 wird ansprechend angezeigt.
Dazu kombinieren wir: .m²_blue .m²_box
Dienste wie z.B. Github, aber auch Magentacloud, zeigen Markdown-Dateien automatisch als ordentlich aussehendes HTML an. Aber jeder kann selbst Tools einzusetzen, die optisch ansprechende Dokumente in vielen verschiedenen Formaten erzeugen können. Ich habe beschlossen, alle Ausgaben als HTML- und daraus erzeugte PDF-Dateien zu erstellen. So werden beide mit CSS formatiert. Andere Personen können natürlich auch von Pandoc direkt PDF-, odt- oder epub-Dateien erzeugen lassen. Zu den Möglichkeiten siehe hier.]
Mein grundsätzlicher Werkzeugkasten (Toolchain) sieht wie folgt aus:
Pandoc alleine erzeugt eine korrekte, aber nicht so
hübsche HTML-Datei. Aber man kann mit der Kommandozeilenoption
-H zusätzliche Dateien 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.
Natürlich verfügt Pandoc noch über sehr viel mehr
Koimmandozeilenparameter.
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 als die HTML-Seite gestalten, da dabei
@media print { ... } beachtet wird. Selbst Papiergrößen in
CSS werden millimetergenau berücksichtigt. Bei der Konvertierung werden
Links 1:1 übernommen.
Inzwischen werden bei mir mehrere Dateien (teilweise dynamisch gewählt und erzeugt) inkludiert, die CSS-Zeilen regelmäßig ergänzt, sowie der Aufruf von Pandoc und Chrome per Skript automatisiert.
Dazu habe ich mir ein Tool mdmachine.py geschrieben, das diese Aufgaben (und noch einiges mehr wie eine Navigationsspalte, sitemap, neueste Artikel usw.) erledigt. Außerdem enthält das Tool einen Präprozessor, der die Markdowndatei vor allen anderen Tools einliest und einige Aufgaben übernimmt wie das Ausführen von Programmcode, Füllen einer Minidatenbank mit Code und Ausführungsergebnissen (zur Beschleunigung), dynamisches Einbinden weiterer Markdown-Dateien usw.
Insgesamt arbeite ich also mit Folgendem:
Die Vorgehensweise wird hier ausführlicher dokumentiert.