Mein Blog spricht jetzt auch Markdown
allerleidabei gibt es jetzt zusätzlich als Markdown-Ausgabe. Damit lässt sich der Blog auch in BonBon lesen – einem Browser, der Markdown statt HTML darstellt.
Die Markdown-Dateien entstehen automatisch beim Hugo-Build. Jeder Beitrag bekommt neben seiner HTML-Version eine index.md im selben Verzeichnis. Dadurch funktionieren relative Bildpfade weiterhin.
Eine eigene Markdown-Startseite listet die Beiträge mit Veröffentlichungsdatum auf.
Markdown-Ausgabe mit Hugo
In der hugo.toml sind zwei zusätzliche Ausgabeformate definiert: Markdown für die Seiten und OPML für das BonBon-Inhaltsverzeichnis. Vorhandene Konfigurationsabschnitte müssen entsprechend ergänzt werden.
[outputs]
home = ["HTML", "RSS", "Markdown", "BonBonTOC"]
section = ["HTML", "RSS", "Markdown"]
page = ["HTML", "Markdown"]
[mediaTypes."text/markdown"]
suffixes = ["md"]
[outputFormats.Markdown]
mediaType = "text/markdown"
baseName = "index"
isPlainText = true
isHTML = false
[mediaTypes."text/x-opml"]
suffixes = ["opml"]
[outputFormats.BonBonTOC]
mediaType = "text/x-opml"
baseName = "toc"
path = ".well-known"
isPlainText = true
notAlternative = true
Dazu braucht Hugo eigene Templates. Eine einfache Vorlage für einzelne Markdown-Seiten liegt in layouts/_default/single.md:
---
title: {{ .Title | jsonify }}
{{ with .Description }}description: {{ . | jsonify }}
{{ end }}{{ if not .Date.IsZero }}pubDate: {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | jsonify }}
{{ end }}link: {{ .Permalink | jsonify }}
---
# {{ .Title }}
{{ if not .Date.IsZero }}Veröffentlicht am {{ .Date.Format "02.01.2006" }}
{{ end }}{{ .RenderShortcodes }}
RenderShortcodes verarbeitet Hugo-Shortcodes und erhält das umgebende Markdown. Für Shortcodes, die normalerweise HTML erzeugen, braucht es passende Markdown-Vorlagen unter layouts/shortcodes/, beispielsweise quote.md.
Bei mir bleiben Zitate dadurch Zitate und die Blogroll wird zur Linkliste. Eingebettete HTML-Medien bekommen einen Verweis auf die vollständige Darstellung im normalen Browser. BonBon entfernt HTML aus Markdown-Seiten.
Zusätzlich schreibt meine Umsetzung bekannte interne Seitenlinks auf ihre Markdown-Ziele um.
Eine Markdown-Startseite mit Datum
BonBon zeigt das Veröffentlichungsdatum aus dem pubDate-Metadatum nicht automatisch im Beitrag an. Deshalb steht es zusätzlich als Text unter der Überschrift. Auch die Übersicht bekommt sichtbare Datumsangaben.
Das Template layouts/index.md:
---
title: {{ .Title | jsonify }}
link: {{ .Permalink | jsonify }}
---
# {{ .Title }}
{{ .Site.Params.homeInfoParams.Content }}
{{ range (where .Site.RegularPages "Section" "ne" "talkshows").ByDate.Reverse }}
{{- $title := .Title }}
{{- $date := .Date }}
{{- with .OutputFormats.Get "Markdown" }}
- {{ if not $date.IsZero }}{{ $date.Format "02.01.2006" }} · {{ end }}[{{ $title }}]({{ .Permalink }})
{{ end }}
{{- end }}
Für Bereichsübersichten lässt sich das Prinzip in layouts/_default/list.md übernehmen. Dort wird statt .Site.RegularPages die Seitensammlung .RegularPagesRecursive verwendet.
Seiten ohne Datum bleiben undatiert. Hugos Regeln für Entwürfe und die Aufnahme in Seitenlisten gelten weiterhin.
Navigation mit OPML
Unter .well-known/toc.opml liegt ein automatisch erzeugtes Inhaltsverzeichnis. BonBon lädt es im Hintergrund und kann daraus die Vor-/Zurück-Navigation zwischen den Seiten ableiten. Eigene Angaben für urlPrev und urlNext sind dafür nicht erforderlich.
Das Template layouts/index.bonbontoc.opml:
<?xml version="1.0" encoding="UTF-8"?>
<opml version="2.0">
<head>
<title>{{ .Site.Title | htmlEscape }} – Markdown</title>
</head>
<body>
<outline
text="Start"
type="link"
url="{{ (.OutputFormats.Get "Markdown").Permalink | htmlEscape }}" />
{{ range (where .Site.RegularPages "Section" "ne" "talkshows").ByDate.Reverse }}
{{- $title := .Title }}
{{- with .OutputFormats.Get "Markdown" }}
<outline
text="{{ $title | htmlEscape }}"
type="link"
url="{{ .Permalink | htmlEscape }}" />
{{ end }}
{{- end }}
</body>
</opml>
Die Reihenfolge beginnt mit der Startseite, gefolgt von den Beiträgen – neueste zuerst – und undatierten Seiten wie der Blogroll.
BonBon kennt außerdem .well-known/bonbon.json, etwa für Suchdienste oder automatische Aktualisierungen. Da ich diese Funktionen bisher nicht anbiete, enthält meine Datei unter static/.well-known/bonbon.json lediglich:
{}
Diese Datei ist optional.
Auslieferung durch nginx
Markdown muss mit dem Inhaltstyp text/markdown; charset=utf-8 ausgeliefert werden. Für OPML verwende ich application/xml; charset=utf-8.
Eine Anfrage mit Accept: text/markdown bekommt eine Weiterleitung auf /index.md. Normale HTML-Anfragen erhalten die gewohnte Startseite.
Für dieses Verhalten wird im nginx-server-Block zusätzlich eine Regel für die Startadresse ergänzt.
# Den bisherigen Block „location = /“ durch diesen ersetzen:
location / {
add_header Vary Accept always;
# Markdown-Anfragen für Verzeichnis-URLs weiterleiten:
# / → /index.md
# /posts/beitrag/ → /posts/beitrag/index.md
if ($http_accept ~* "text/markdown") {
rewrite ^(.*/)$ https://www.allerleidabei.de$1index.md redirect;
}
# HTML und andere Dateien weiterhin regulär ausliefern.
try_files $uri $uri/ =404;
}
# Die Blöcke für .md und .opml evtl. ergänzen falls nicht bereits vorhanden.
location ~ \.md$ {
types { }
default_type text/markdown;
charset utf-8;
charset_types text/markdown;
try_files $uri =404;
}
location ~ \.opml$ {
types { }
default_type application/xml;
charset utf-8;
charset_types application/xml;
try_files $uri =404;
}