markdown: Markdown-to-html NGINX-Modul

Erfordert den Pro-Plan (oder höher) des GetPageSpeed NGINX Extras-Abonnements.

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

RedHat Enterprise Linux 7, 8, 9 und 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 und Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 und Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-markdown

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-markdown

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_markdown_filter_module.so;

Dieses Dokument beschreibt nginx-module-markdown v1.0.0, veröffentlicht am 15. Februar 2026.

Ein NGINX-Modul, das Markdown-Dateien dynamisch in HTML umwandelt, mit Unterstützung für YAML-Frontmatter, GFM-Erweiterungen und anpassbare Vorlagen.

Basierend auf cmark-gfm (GitHub Flavored Markdown) ermöglicht dieses Modul das Bereitstellen von Markdown-Dokumentationen direkt von NGINX mit vollständiger SEO-Unterstützung durch dynamische Metadatenextraktion.

Funktionen

Funktion	Beschreibung
Dynamische Umwandlung	Servieren Sie `.md`-Dateien als HTML ohne Vorverarbeitung
YAML-Frontmatter	Extrahieren Sie Metadaten für dynamische Titel, Beschreibungen und SEO-Tags
Vorlagensystem	Wickeln Sie Inhalte in benutzerdefinierte HTML-Vorlagen mit Platzhalterersetzung
GFM-Erweiterungen	Tabellen, Durchstreichungen, Aufgabenlisten, Autolinks und Tag-Filterung
Null Laufzeitabhängigkeiten	Statisch verlinkt, keine externen Dienste erforderlich
Proxy-Unterstützung	Funktioniert mit upstream Markdown-Dateien, nicht nur mit lokalen Dateien

Schnellstart

location ~ \.md$ {
    markdown_filter on;
    markdown_template /etc/nginx/templates/page.html;
}

Direktivenreferenz

markdown_filter


Syntax	`markdown_filter on \\| off;`
Standard	`off`
Kontext	`location`

Aktiviert oder deaktiviert die Umwandlung von Markdown in HTML.

markdown_template


Syntax	`markdown_template <path>;`
Standard	—
Kontext	`location`

Pfad zu einer HTML-Vorlagendatei. Verwenden Sie den Platzhalter {{content}}, um das gerenderte Markdown einzufügen.

markdown_front_matter


Syntax	`markdown_front_matter on \\| off;`
Standard	`off`
Kontext	`location`

Analysiert YAML-Frontmatter aus Markdown-Dateien, um die Platzhalterersetzung in Vorlagen zu ermöglichen.

markdown_unsafe


Syntax	`markdown_unsafe on \\| off;`
Standard	`off`
Kontext	`location`

Erlaubt rohen HTML-Durchlauf im Markdown-Inhalt. Vorsicht verwenden bei nicht vertrauenswürdigen Eingaben.

markdown_gfm_tagfilter


Syntax	`markdown_gfm_tagfilter on \\| off;`
Standard	`off`
Kontext	`location`

Filtert gefährliche HTML-Tags (<script>, <iframe>, <style>, etc.) aus der Ausgabe.

markdown_gfm_tasklist


Syntax	`markdown_gfm_tasklist on \\| off;`
Standard	`off`
Kontext	`location`

Aktiviert GitHub-Style Aufgabenlisten-Checkboxen: - [ ] und - [x].

markdown_gfm_strikethrough


Syntax	`markdown_gfm_strikethrough on \\| off;`
Standard	`off`
Kontext	`location`

Aktiviert die Syntax ~~Durchstreichung~~.

markdown_gfm_autolink


Syntax	`markdown_gfm_autolink on \\| off;`
Standard	`off`
Kontext	`location`

Konvertiert automatisch nackte URLs und E-Mail-Adressen in klickbare Links.

Vorlagensystem

Vorlagen wickeln gerendertes Markdown in benutzerdefinierte HTML ein. Verwenden Sie {{content}}, um zu kennzeichnen, wo das konvertierte Markdown erscheint:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Dokumentation</title>
    <link rel="stylesheet" href="/css/docs.css">
</head>
<body>
    <main>{{content}}</main>
</body>
</html>

YAML-Frontmatter

Aktivieren Sie markdown_front_matter, um Metadaten aus Markdown-Dateien zu extrahieren und die Platzhalter in Vorlagen dynamisch zu ersetzen. Wichtig für die SEO-Optimierung.

Beispiel Markdown-Datei

---
title: Einstiegshandbuch
meta:
  description: Erfahren Sie, wie Sie das Modul installieren und konfigurieren
  keywords: nginx, markdown, dokumentation
  robots: index, follow
author: Dokumentationsteam
---

## Einstieg

Willkommen zur Dokumentation.

Beispiel Vorlage

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>{{title}}</title>
    <meta name="description" content="{{meta.description}}">
    <meta name="keywords" content="{{meta.keywords}}">
    <meta name="robots" content="{{meta.robots}}">
    <meta name="author" content="{{author}}">
</head>
<body>
    <article>{{content}}</article>
</body>
</html>

Frontmatter-Funktionen

Verschachtelte Schlüssel — Zugriff mit Punktnotation: {{meta.description}}
Zitatbehandlung — Umgebende Anführungszeichen werden automatisch entfernt
Sanfter Fallback — Fehlende Werte werden als leere Strings gerendert
Rückwärtskompatibel — Dateien ohne Frontmatter funktionieren normal

GFM-Erweiterungen

Wenn mit cmark-gfm (Standard in GetPageSpeed-Paketen) gebaut, sind diese Erweiterungen verfügbar:

Erweiterung	Direktive	Beispiel
Tabellen	Immer aktiviert	`\| A \| B \|`
Durchstreichung	`markdown_gfm_strikethrough on`	`~~gelöscht~~`
Aufgabenlisten	`markdown_gfm_tasklist on`	`- [x] Erledigt`
Autolinks	`markdown_gfm_autolink on`	`https://example.com`
Tag-Filter	`markdown_gfm_tagfilter on`	Sanitizes `<script>`, `<iframe>`, etc.

Beispielkonfigurationen

Dokumentationsseite

Servieren Sie Markdown-Dokumentationen mit ordnungsgemäßen SEO-Metadaten:

location /docs/ {
    markdown_filter on;
    markdown_front_matter on;
    markdown_template /etc/nginx/templates/docs.html;
    markdown_gfm_tasklist on;
    markdown_gfm_autolink on;
}

Blog mit Upstream-CMS

Verarbeiten Sie Markdown von einem headless CMS:

location /blog/ {
    proxy_pass http://cms-backend;
    markdown_filter on;
    markdown_front_matter on;
    markdown_template /etc/nginx/templates/blog.html;
}

Wiki mit Benutzerinhalten

Erlauben Sie benutzergenerierte Inhalte mit HTML-Sanitierung:

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # HTML erlauben, aber gefährliche Tags filtern
    markdown_template /etc/nginx/templates/wiki.html;
}

Vollständige Konfiguration

location ~ \.md$ {
    markdown_filter on;
    markdown_front_matter on;
    markdown_template /etc/nginx/templates/docs.html;
    markdown_gfm_strikethrough on;
    markdown_gfm_tasklist on;
    markdown_gfm_autolink on;
    markdown_gfm_tagfilter on;
}