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.

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;
    }