Markdown und YAML

Markdown

Zettlr zuerst einmal ein Markdown-Editor (von »Markup«, übersetzt »Textauszeichnung«). Das bedeutet, mit einer überschaubaren Anzahl Markup-Zeichen weist man Bereiche des Texts als Überschrift aus, als Zitat, setzt sie fett oder bindet Bilder ein.

Die Dokumente sind im Prinzip erst einmal nur Text. Das bedeutet, wenn man bisher nur mit Word gearbeitet hat, muss man etwas umdenken, denn das Aussehen des Endprodukts ist vom Schreibvorgang getrennt. (Persönlich halte ich das für eine gute Sache.)

Typische Markdown-Syntax sieht folgendermaßen aus:

#   Überschrift 1. Ebene
##  Überschrift 2. Ebene
### Überschrift 3. Ebene

* Nicht-nummerierte Liste

1. Nummerierte
2. Liste

**Fett**
_Kursiv_

Weitere Informationen über Markdown und hilfreiche Ressourcen finden sich hier:

• https://spec.commonmark.org/0.30/
• https://www.markdownguide.org/cheat-sheet/
• Meine Markdown-Ressourcen-Sammlung

YAML

Um Markdown-Dokumenten Metadaten hinzuzufügen, wird »Yet Another Markup Language« verwendet, kurz YAML. Ein YAML-Header gibt mir selbst Hinweise darauf, wann ich einen Text erstellt habe, wie er heißt, welche Inhalte er hat (ohne ihn erst noch einmal lesen zu müssen) und enthält andere Angaben, die ich selbst dort sehen möchte.

Beispielsweise sieht der YAML-Block meiner Aufgabe zur Kollokationsanalyse folgendermaßen aus:

Der von mir eingetragene Titel wird von Zettlr verwendet, um den Text im Programm anzuzeigen …

… aber bei der Ausgabe als PDF automatisch als Überschrift angezeigt.

Auch Name und Datumsangabe werden aus dem YAML-Block übernommen.

Der etwas kryptisch wirkende untere Block definiert das Aussehen von Header & Footer:

Die Variable fancyhead[C] definiert, dass der Titel zentriert gesetzt wird. Hätte ich den Titel stattdessen in fancyhead[R] oder fancyhead[L] eingegeben, wäre er, je nachdem rechts- bzw. linksbündig gesetzt.

---

fancyfoot[R] setzt das Datum des Dokuments rechtsbündig. Die Seitennummer wird, in diesem Beispiel, nicht über den YAML-Header konfiguriert. Sie ist in der Konfigurationsdatei für die PDF-Ausgabe bereits vorkonfiguriert. Diese Voreinstellungen sind im Normalfall so sinnvoll, dass sie nicht verändert werden müssen.

Solche Bereiche sehen auf den ersten Blick ‚schwierig‘ aus, wenn man gewohnt ist, das Aussehen eines Dokuments in Word zusammenzuklicken. Allerdings plane ich auch hier noch Vorlagen für Studierende der Fakultät zusammenzustellen, die man dann einfach übernehmen kann.

Snippets

Auf den ersten Blick mag der YAML-Block lästig und unhandlich wirken. Man muss diesen nicht aber jedes Mal von Hand tippen, denn Zettlr besitzt eine Funktion, die sich »Snippets« nennt.

Dort legt man kurze Schnipsel an, die man innerhalb Zettlr wiederverwendet. Man ruft dieses Schnipselverzeichnis auf, in dem man nur einen Doppelpunkt : nach einem Leerzeichen eintippt und wählt den benötigten Schnipsel aus Menü aus:

Der Schnipsel für den YAML-Block enthält beispielsweise einige Variablen¹, die beim Einfügen ins Dokument automatisch ergänzt werden:

Bilder und das Bildverzeichnis

Bilder

Auch Bilder werden in Markdown-Editoren, so auch Zettlr, über einen kleinen Markup-Befehl repräsentiert und dargestellt. Er besteht aus zwei Teilen.

1. Die Beschreibung des Bildes. Sie wird bei der Ausgabe als PDF zur Bildunterschrift.
2. Der Speicherort des Bildes

Zettlr erstellt diese Zeile automatisch, wenn man ein Bild aus der Zettlr-Seitenleiste in den Editor zieht. Nur bei der Bildbeschreibung muss man dann noch von Hand nacharbeiten.

In der PDF-Ausgabe sieht das Ganze dann so aus:

Abbildungsverzeichnis

Das Abbildungsverzeichnis fügt man in Zettlr mit einem einzigen LaTeX-Befehl hinzu: Diesen setzt man an die Stelle des Dokuments, wo das Abbildungsverzeichnis erscheinen soll. Also zumeist am Ende des Dokuments.

Auch diesen kurzen Befehl habe ich mir als Snippet angelegt, damit ich ihn mir nicht merken muss.

In der PDF-Ausgabe sieht das ganze dann wie folgt aus:

Weiteres

Einen Seitenumbruch erzwingen

Manchmal kann es für die Übersichtlichkeit sinnvoll sein, einen Seitenumbruch zu erzwingen. Zum Beispiel zwischen dem Ende des Texts, dem Abbildungsverzeichnis und der Quellenliste. Dies erreicht man, in dem man an die gewünschte Stelle den Befehl …

\pagebreak

\pagebreak

… eingibt.

Auch für diesen Befehl habe ich mir ein Snippet angelegt.

PDF-Einstellungen

Das Aussehen des PDFs, z. B. die Breite der Ränder, oder Überschriften mit oder ohne Nummerierung und andere Details werden über eine Export-Konfiguration definiert. Auf diese werde ich hier nicht mehr eingehen, da auch die von Zettlr mitgelieferten Grundeinstellungen zumeist ausreichend sind. Aber auch sie findet man im »Assets Manager«, in dem sich auch die »Snippets« befinden, und zwar unter dem Reiter »Exporting«.

Für den Export als PDF sucht man nach dem Eintrag mit dem Hinweis »Markdown → PDF«.

Die PDF-Export-Einstellungen anpassen

Ausgabe mit Inhaltsverzeichnis

In den meisten Fällen sind die Grundeinstellungen völlig ausreichend. Möchte man aber zum Beispiel ein Inhaltsverzeichnis unter dem Titel-Block einbinden, muss man die Standard-Konfigurationsdatei im Zettlr-Asset-Manager kopieren und die Zeile …

toc: false # Include a table of contents?

… abändern, zu:

toc: true # Include a table of contents?

Auch die nächste Zeile muss dann eventuell angepasst werden. Sie definiert, welche Überschriften im Inhaltsverzeichnis angezeigt werden.

Wir erinnern uns, in Markdown gibt die Zahl der ›#‹ an, welche Ebene die Überschrift hat. Die Zeile:

toc-depth: 2 # 2 means to only include headings level 1 and 2 in the ToC

schließt die Überschriften der ersten und der zweiten Ebene ein, also:

#  Überschrift 1. Ebene
## Überschrift 2. Ebene

Möchte man 3 Ebenen im Inhaltsverzeichnis anzeigen, ändert man die 2 zur 3.

toc-depth: 3 # 2 means to only include headings level 1 and 2 in the ToC

Eingeschlossen sind nun:

#   Überschrift 1. Ebene
##  Überschrift 2. Ebene
### Überschrift 3. Ebene

Meistens kommt es der Übersichtlichkeit zugute, wenn nur die ersten zwei, maximal die ersten drei Ebenen im Inhaltsverzeichnis angezeigt werden. Das hängt aber vom Thema und der Art des Dokuments ab.

Ein Schritt weiter: Die Dokumentenklasse scrartcl

Um Markdown-Dateien mit Zettlr exportieren zu können, muss man auf dem Rechner, den man zum Export nutzen möchte, die LaTeX-Umgebung installieren. Diese installiert eine ganze Menge nützlicher Erweiterungen gleich mit. So auch das Paket namens »Koma-Script«.

Koma-Script bringt eine ganze Menge nützlicher Einstellungen für akademische Texte mit. Einfach nur die Zeilen …

variables:
  documentclass: scrartcl

… zur Konfigurationsdatei für den PDF-Export hinzuzufügen hat zur Folge, dass alle Überschriften in einem serifenlosen Font gesetzt werden, während der Textkörper weiterhin einen Serifen-Font nutzt — üblich und von der Fakultät vorgegeben ist Times New Roman. Das gibt dem Dokument ein sauberes, etwas moderneres Aussehen.

Alle meine PDF-Export-Konfigurations-Beispiele nutzen den Koma-Script-Dokumententyp scrartcl.

Fazit oder tl;dr

Zettlrs System aus Snippets und einem robusten Export mit LaTeX im Hintergrund ermöglicht es, sich rein auf den Text zu konzentrieren.

Zu Beginn der Arbeit fügt man den YAML-Block mit einmal Drücken des Doppelpunkts aus dem Snippets-Menü ein und füllt nur noch Titel (und Schlüsselwörter) aus, bzw. ergänzt jene Metadaten, die man im Endprodukt sehen möchte.

Bilder zieht man mit der Maus ins Dokument und ergänzt die Bildbeschreibungen.

Mit einem weiteren Drücken des Doppelpunkts fügt man, aus dem Snippets-Menü, ein Bildverzeichnis an der Stelle ein, an der es im Dokument auftauchen soll.

Das Endergebnis wirkt mit wenig Aufwand sauber und ordentlich formatiert.

Es sind auch komplexere Layouts möglich, z. B. mit einem ausführlichen Deckblatt, aber für den alltäglichen Bedarf ist dieses einfache Ausgabeformat ausreichend.

Gibt man im YAML-Header nicht nur seinen Namen und die E-Mail-Adresse, sondern auch sinnvolle Schlüsselwörter ein, werden diese beim PDF-Export übergeben, genau wie die Gliederung. Das PDF besitzt daher sinnvolle Metadaten und kann über das Inhaltsverzeichnis, sofern aktiviert, leicht navigiert werden.

1. Die »ID« ist an dieser Stelle nicht wichtig. Sie kommt dann ins Spiel, wenn man Zettlr als Wissensmanagementtool, oder auch »Zettelkasten« nach Niklas Luhmann verwendet. ↩︎

---

Weitere Ressourcen

• Meine Snippets — auf GitLab @ KIT
• Meine Exportkonfigurationen — auf GitLab @ KIT
• Diese (und in der Zukunft auch weitere) Anleitung(en) als PDF — auf GitLab @ KIT

PDF-Download

Nachweise