2.3 – Markdown-Schnipsel

Endet file auf .md, wird die Datei beim Bauen zu HTML umgewandelt. Gerendert wird GitHub-Flavored Markdown, eingebettetes HTML ist erlaubt, und Platzhalter funktionieren wie sonst auch:

## {{siteTitle}}
 
Notizen aus einer _kleinen_ Stadt.
 
- <a href="{{root}}/ueber">Über diese Site</a>
- <a href="{{root}}/kontakt">Kontakt</a>

Die Box unten links auf dieser Website ist genau so gemacht — mit Markdown-Links, seit das Plugin die maskierte Form erkennt. Warum das eine Weile nicht ging und wann der HTML-Anker weiterhin der sichere Weg ist, steht gleich unten.

Was dort nicht geht

Ein Markdown-Schnipsel läuft nicht durch die Inhaltspipeline von Quartz. Was dort stehen bleibt, wie es geschrieben ist:

Schreibweise	Was daraus wird
[[Wikilink]]	bleibt als Text stehen
> [!note]	wird ein gewöhnliches Zitat, kein Callout
![[Bild.png]]	bleibt als Text stehen
[Text](ziel)	wird ein Link — normales Markdown funktioniert
[Text]({{root}}/ziel)	wird ein Link mit eingesetztem Wert — siehe unten
**fett**, Listen, Tabellen, Überschriften	funktionieren

Der Grund steht in 1.3: Das Plugin ist eine reine Komponente. Es wird gefragt, wenn Quartz das Layout baut — und da ist die Verarbeitung des Inhalts längst gelaufen.

Ein Platzhalter im Linkziel — die Geschichte dazu

Dass die Zeile oben funktioniert, ist noch nicht lange so, und der Grund lohnt sich zu kennen.

Erst wird Markdown zu HTML gerendert, dann werden Platzhalter ersetzt (1.3). Beim Rendern macht der Markdown-Renderer aus einem Linkziel eine Adresse und maskiert dabei die geschweiften Klammern zu %7B%7B und %7D%7D. Die Ersetzung suchte danach nach {{root}} und fand nichts; im HTML stand dann wörtlich %7B%7Broot%7D%7D.

Im href eines HTML-Elements passierte das nie — dort bleibt die Adresse, wie sie ist, bis die Ersetzung an sie kommt. Zwei Schreibweisen, die in der Quelle gleichwertig aussehen, verhielten sich also verschieden.

Behoben, aber nicht rückwirkend

Das Plugin erkennt die maskierte Form inzwischen und setzt beide Schreibweisen gleich. Wer eine ältere Fassung installiert hat, schreibt Links im Schnipsel weiter als HTML-Anker: <a href="{{root}}/ueber">Über diese Site</a>. Das funktioniert in jeder Fassung.

Gefunden erst beim Veröffentlichen

Solange eine Site an der Wurzel liegt, fällt ein kaputter Pfad kaum auf. Unter einem Unterpfad — auf GitHub Pages der Normalfall — führte jeder dieser Links ins Leere. Genau so kam es heraus: beim ersten Deploy dieser vier Websites, 14 tote Links auf einmal.

Links im Schnipsel brauchen {{root}}

Ein Schnipsel steht auf allen Seiten, auch auf denen zwei Ebenen tief. Ein Link auf /ueber zeigt an der Wurzel des Servers vorbei, sobald die Site unter einem Unterpfad liegt. {{root}}/ueber rechnet den Weg von jeder Seite aus richtig aus; siehe 4.2 – root und Adressen.

HTML oder Markdown?

Markdown lohnt sich, sobald der Schnipsel Fließtext, eine Liste oder Links enthält — es ist kürzer und liest sich beim Bearbeiten besser. HTML lohnt sich, sobald es um Struktur geht, die Markdown nicht kennt: ein <svg>, ein Bild mit zwei Fassungen für hell und dunkel, ein Element mit einer eigenen Klasse.