markdown: Módulo NGINX para convertir Markdown a HTML

Requiere el plan Pro (o superior) de la suscripción GetPageSpeed NGINX Extras.

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

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

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

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_markdown_filter_module.so;

Este documento describe nginx-module-markdown v1.0.0 lanzado el 15 de febrero de 2026.

Un módulo NGINX que transforma archivos Markdown a HTML al vuelo con soporte para YAML front matter, extensiones GFM y plantillas personalizables.

Construido sobre cmark-gfm (GitHub Flavored Markdown), este módulo permite servir documentación Markdown directamente desde NGINX con soporte completo para SEO a través de la extracción dinámica de metadatos.

Características

Característica	Descripción
Conversión al vuelo	Sirve archivos `.md` como HTML sin preprocesamiento
YAML front matter	Extrae metadatos para títulos, descripciones y etiquetas SEO dinámicas
Sistema de plantillas	Envuelve contenido en plantillas HTML personalizadas con sustitución de marcadores de posición
Extensiones GFM	Tablas, tachado, listas de tareas, enlaces automáticos y filtrado de etiquetas
Sin dependencias en tiempo de ejecución	Enlazado estáticamente, no se requieren servicios externos
Soporte para proxy	Funciona con archivos markdown de upstream, no solo con archivos locales

Inicio Rápido

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

Referencia de Directivas

markdown_filter


Sintaxis	`markdown_filter on \\| off;`
Predeterminado	`off`
Contexto	`location`

Habilita o deshabilita la conversión de Markdown a HTML.

markdown_template


Sintaxis	`markdown_template <path>;`
Predeterminado	—
Contexto	`location`

Ruta a un archivo de plantilla HTML. Usa el marcador de posición {{content}} para insertar Markdown renderizado.

markdown_front_matter


Sintaxis	`markdown_front_matter on \\| off;`
Predeterminado	`off`
Contexto	`location`

Analiza el YAML front matter de los archivos Markdown para habilitar la sustitución de marcadores de posición en la plantilla.

markdown_unsafe


Sintaxis	`markdown_unsafe on \\| off;`
Predeterminado	`off`
Contexto	`location`

Permite el paso de HTML sin procesar en el contenido Markdown. Usar con precaución en entradas no confiables.

markdown_gfm_tagfilter


Sintaxis	`markdown_gfm_tagfilter on \\| off;`
Predeterminado	`off`
Contexto	`location`

Filtra etiquetas HTML peligrosas (<script>, <iframe>, <style>, etc.) de la salida.

markdown_gfm_tasklist


Sintaxis	`markdown_gfm_tasklist on \\| off;`
Predeterminado	`off`
Contexto	`location`

Habilita casillas de verificación de listas de tareas al estilo de GitHub: - [ ] y - [x].

markdown_gfm_strikethrough


Sintaxis	`markdown_gfm_strikethrough on \\| off;`
Predeterminado	`off`
Contexto	`location`

Habilita la sintaxis ~~tachado~~.

markdown_gfm_autolink


Sintaxis	`markdown_gfm_autolink on \\| off;`
Predeterminado	`off`
Contexto	`location`

Convierte automáticamente URLs y direcciones de correo electrónico en enlaces clicables.

Sistema de Plantillas

Las plantillas envuelven el Markdown renderizado en HTML personalizado. Usa {{content}} para marcar dónde aparece el Markdown convertido:

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

YAML Front Matter

Habilita markdown_front_matter para extraer metadatos de los archivos Markdown y sustituir dinámicamente los marcadores de posición de la plantilla. Esencial para la optimización SEO.

Ejemplo de Archivo Markdown

---
title: Guía de Inicio Rápido
meta:
  description: Aprende a instalar y configurar el módulo
  keywords: nginx, markdown, documentación
  robots: index, follow
author: Equipo de Documentación
---

## Guía de Inicio Rápido

Bienvenido a la documentación.

Ejemplo de Plantilla

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

Características del Front Matter

Claves anidadas — Acceso con notación de punto: {{meta.description}}
Manejo de comillas — Las comillas alrededor se eliminan automáticamente
Fallback elegante — Los valores faltantes se renderizan como cadenas vacías
Compatible hacia atrás — Los archivos sin front matter funcionan normalmente

Extensiones GFM

Cuando se construye con cmark-gfm (predeterminado en los paquetes de GetPageSpeed), estas extensiones están disponibles:

Extensión	Directiva	Ejemplo
Tablas	Siempre habilitado	`\| A \| B \|`
Tachado	`markdown_gfm_strikethrough on`	`~~eliminado~~`
Listas de Tareas	`markdown_gfm_tasklist on`	`- [x] Hecho`
Enlaces Automáticos	`markdown_gfm_autolink on`	`https://example.com`
Filtro de Etiquetas	`markdown_gfm_tagfilter on`	Sanitiza `<script>`, `<iframe>`, etc.

Ejemplos de Configuración

Sitio de Documentación

Sirve documentación Markdown con metadatos SEO adecuados:

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 con CMS de Upstream

Procesa Markdown desde un CMS sin cabeza:

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

Wiki con Contenido de Usuarios

Permite contenido contribuido por usuarios con sanitización de HTML:

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # Permite HTML pero filtra etiquetas peligrosas
    markdown_template /etc/nginx/templates/wiki.html;
}

Configuración Completa

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