markdown: Module NGINX pour Markdown vers HTML

Nécessite le plan Pro (ou supérieur) de l'abonnement GetPageSpeed NGINX Extras.

Installation

Vous pouvez installer ce module dans n'importe quelle distribution basée sur RHEL, y compris, mais sans s'y limiter :

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 et 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

Activez le module en ajoutant ce qui suit en haut de /etc/nginx/nginx.conf :

load_module modules/ngx_markdown_filter_module.so;

Ce document décrit nginx-module-markdown v1.0.0 publié le 15 février 2026.

Un module NGINX qui transforme les fichiers Markdown en HTML à la volée avec support pour les métadonnées YAML, les extensions GFM et des modèles personnalisables.

Construit sur cmark-gfm (GitHub Flavored Markdown), ce module permet de servir la documentation Markdown directement depuis NGINX avec un support SEO complet grâce à l'extraction dynamique des métadonnées.

Fonctionnalités

Fonctionnalité	Description
Conversion à la volée	Servez des fichiers `.md` en tant que HTML sans prétraitement
Métadonnées YAML	Extrayez des métadonnées pour des titres, descriptions et balises SEO dynamiques
Système de modèles	Enveloppez le contenu dans des modèles HTML personnalisés avec substitution de placeholders
Extensions GFM	Tableaux, barré, listes de tâches, liens automatiques et filtrage de balises
Aucune dépendance d'exécution	Lié statiquement, aucun service externe requis
Support proxy	Fonctionne avec des fichiers markdown en amont, pas seulement des fichiers locaux

Démarrage rapide

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

Référence des directives

markdown_filter


Syntaxe	`markdown_filter on \\| off;`
Par défaut	`off`
Contexte	`location`

Active ou désactive la conversion de Markdown en HTML.

markdown_template


Syntaxe	`markdown_template <path>;`
Par défaut	—
Contexte	`location`

Chemin vers un fichier de modèle HTML. Utilisez le placeholder {{content}} pour insérer le Markdown rendu.

markdown_front_matter


Syntaxe	`markdown_front_matter on \\| off;`
Par défaut	`off`
Contexte	`location`

Analyse les métadonnées YAML des fichiers Markdown pour permettre la substitution de placeholders dans les modèles.

markdown_unsafe


Syntaxe	`markdown_unsafe on \\| off;`
Par défaut	`off`
Contexte	`location`

Autorise le passage de HTML brut dans le contenu Markdown. À utiliser avec prudence sur des entrées non fiables.

markdown_gfm_tagfilter


Syntaxe	`markdown_gfm_tagfilter on \\| off;`
Par défaut	`off`
Contexte	`location`

Filtre les balises HTML dangereuses (<script>, <iframe>, <style>, etc.) de la sortie.

markdown_gfm_tasklist


Syntaxe	`markdown_gfm_tasklist on \\| off;`
Par défaut	`off`
Contexte	`location`

Active les cases à cocher de liste de tâches au style GitHub : - [ ] et - [x].

markdown_gfm_strikethrough


Syntaxe	`markdown_gfm_strikethrough on \\| off;`
Par défaut	`off`
Contexte	`location`

Active la syntaxe ~~barré~~.

markdown_gfm_autolink


Syntaxe	`markdown_gfm_autolink on \\| off;`
Par défaut	`off`
Contexte	`location`

Convertit automatiquement les URL et adresses e-mail nues en liens cliquables.

Système de modèles

Les modèles enveloppent le Markdown rendu dans du HTML personnalisé. Utilisez {{content}} pour marquer où le Markdown converti apparaît :

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

Métadonnées YAML

Activez markdown_front_matter pour extraire des métadonnées des fichiers Markdown et substituer dynamiquement les placeholders des modèles. Essentiel pour l'optimisation SEO.

Exemple de fichier Markdown

---
title: Guide de démarrage
meta:
  description: Apprenez à installer et configurer le module
  keywords: nginx, markdown, documentation
  robots: index, follow
author: Équipe de documentation
---

## Démarrage

Bienvenue dans la documentation.

Exemple de modèle

<!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>

Fonctionnalités des métadonnées

Clés imbriquées — Accès avec notation par points : {{meta.description}}
Gestion des guillemets — Les guillemets environnants sont automatiquement supprimés
Retour gracieux — Les valeurs manquantes s'affichent comme des chaînes vides
Compatible avec les versions précédentes — Les fichiers sans métadonnées fonctionnent normalement

Extensions GFM

Lorsqu'il est construit avec cmark-gfm (par défaut dans les paquets GetPageSpeed), ces extensions sont disponibles :

Extension	Directive	Exemple
Tableaux	Toujours activé	`\| A \| B \|`
Barré	`markdown_gfm_strikethrough on`	`~~supprimé~~`
Listes de tâches	`markdown_gfm_tasklist on`	`- [x] Fait`
Liens automatiques	`markdown_gfm_autolink on`	`https://example.com`
Filtre de balises	`markdown_gfm_tagfilter on`	Assainit `<script>`, `<iframe>`, etc.

Exemples de configurations

Site de documentation

Servez la documentation Markdown avec des métadonnées SEO appropriées :

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 avec CMS en amont

Traitez le Markdown d'un CMS sans tête :

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

Wiki avec contenu utilisateur

Autorisez le contenu contribué par les utilisateurs avec assainissement HTML :

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # Autoriser HTML mais filtrer les balises dangereuses
    markdown_template /etc/nginx/templates/wiki.html;
}

Configuration complète

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