Bloggen mit Markdown

#Problem

Das Problem war, herauszufinden, wie man die Artikel generiert. Programmiert man ein Backend und nutzt einen Rich-Text-Editor (RTE), wie in Wordpress. Dann fügt man das generierte HTML manuell in jede HTML-Seite ein? Könnte man machen, ist aber:

1. fehleranfällig und aufgeblasen, da RTE manchmal unsichtbare und unnötige Dinge in die Darstellung reinkodiert, somit auch die Datei vergrößert.
2. schlecht archivierbar, weil RTE-Datei und Website muss parallel archiviert werden.
3. aufwendig

So blieb mir nur ein anderer Weg. Markdown. Das schien der perfekte Weg zu sein. Dies hat zwar ein paar Nachteile, wie weniger Flexibilität in der Gestaltung, aber dafür ist es sehr robust und nicht fehleranfällig.

Aber wie bekommt man zusätzliche Metadaten wie Titel, Veröffentlichungsdatum, Beschreibung, Open Graph Informationen, wie das Titelbild für soziale Medien in die Artikel rein?

#Lösung

Den Inhalt und die Metadaten in dieselbe Markdown-Dateien schreiben. Diese werden dann beim Build-Process extrahiert. Beispel einer typische Markdown-Datei:

# Hallo
## Überschrift 1

Ich habe keine Ahnung, was **_ich hier mache_**.

Die Metadaten werden als Frontmatter hinzugefügt. Frontmatter ist ein Ansatz zum Speichern von Metadaten, den sich Jekyll ausgedacht hat. Hier legt man alle Metadaten im obere Bereich in derselben Datei ab, diese werden aber durch --- vom eigentlichen Inhalt getrennt.

---
title: "Der Titel"
description: "Die Beschreibung"
---

Die Markdown-Datei würde also aussehen:

---
title: "Der Titel"
description: "Die Beschreibung"
---

# Hallo
## Überschrift 1

Ich habe keine Ahnung, was **_ich hier mache_**.

Aber wie konvertiert man diese in HTML und speichern die Metadaten weg?

#Verarbeitung der Daten

Wie bekommt man das Markdown als Seite im Browser angezeigt? Dafür gibt es zwei NPM-Pakete.

• front-matter zur Erfassung der Metadaten.
• markdown-it für die Umwandlung von Markdown-Inhalten in HTML.

#front-matter

front-matter nimmt den Markdown-Inhalt auf, zerlegt ihn und gibt ein Objekt zurück:

{
  attributes: {
    ...
  },
  body: {
    "..."
  }
}

attributes ist ein Key-Value-Pair aller Metadaten.

body ist der Hauptinhalt, den man in Markdown geschrieben hat. Der Inahlt in body ist noch nicht in HTML umgewandelt. Das muss im nächsten Schritt passieren.

Markdown code:

---
title: Bloggen mit Markdown
description: Wie baut man ein System zum Bloggen mit Markdown auf
---

**Das** ist der Inhalt des Dokuments

wird zu

{
  attributes: {
    title: "Bloggen mit Markdown",
    description: "Wie baut man ein System zum Bloggen mit Markdown auf"
  },
  body: "**Das** ist der Inhalt des Dokuments"
}

Alle Metadaten wurden in einem Objekt zusammengefasst, das man beliebig verwenden kann. Der body-Teil blieb völlig unverändert.

#markdown-it

Jetzt muss man markdown-it verwenden, um das Markdown im body in HTML umzuwandeln. Der grundlegende Code ist relativ einfach:

const md = require("markdown-it")();

const result = md.render("#Das ist die Überschrift");

Jetzt hat man die gerenderten HTML- und Metadaten und könnte diese einfach in einer JSON-Datei speichern. Diese würde so aussehen:

{
  "title": "Bloggen mit Markdown",
  "description": "Wie baut man ein System zum Bloggen mit Markdown auf",
  "body": "<p><b>Das</b> ist der Inhalt des Dokuments.</p>"
}

In Svelte kann man diese dann über fetch abrufen und den Inhalt anzeigen lassen.

#Es wird es bunt

Ein wichtige Teil fehlt: Code Syntax Highlighting!. Es gibt keinen Entwickler-Blog ohne Code-Syntax-Highlightning, um die Code-Snippets besser darzustellen. Dazu gibt es die üblichen Verdächtigen:

• prismjs
• highlight.js

Beide lassen sich mit markdown-it integrieren, um Code Highlightning zur Build-Zeit zu erzeugen. Jedoch habe ich mir für einen Underdog entschieden, der auch viel bietet, und zwar [ShikiJS] (https://github.com/octref/shiki).

Warum? Weil die Syntaxhervorhebung auf die gleiche Weise, wie im VS Code, funktioniert und zwar mit JSON-Konfigurationsdateien. Shiki bietet schon einige vorgefertigte Themes, und vor allem einer meiner Lieblings-Themes Material Palemoon.

Die Integration von shiki mit markdown-it ist genauso einfach gehalten, wie man in der Doku sehen kann. Hier ein Auszug:

const fs = require("fs");
const markdown = require("markdown-it");
const shiki = require("shiki");

shiki
  .getHighlighter({
    theme: "nord",
  })
  .then((highlighter) => {
    const md = markdown({
      html: true,
      highlight: (code, lang) => {
        return highlighter.codeToHtml(code, lang);
      },
    });

    const html = md.render(fs.readFileSync("index.md", "utf-8"));
    const out = `
    <title>Shiki</title>
    <link rel="stylesheet" href="style.css">
    ${html}
    <script src="index.js"></script>
  `;
    fs.writeFileSync("index.html", out);

    console.log("done");
  });

#Mathjax

Und da man als Analyst vielleicht die ein oder andere Formel darstellen muss, habe ich gleich Mathjax mit integriert. Ein JavaScript Paket, welches Formel in allen Browsern rendern kann.

Die Integration war auch wiederum einfach,

import markdown from 'markdown-it';
import markdown_it_mathjax3 from "markdown-it-mathjax3";

const md = markdown.use(mathjax3);

// double backslash is required for javascript strings, but not html input
var result = md.render('Math Rulez! $\\sqrt{3x-1}+(1+x)^2$');

Ausgabe: Math Rulez!

Somit wäre dieser Teil der Website abgeschlossen.