markdown: Módulo NGINX para Markdown-to-html

Requer o plano Pro (ou superior) da assinatura GetPageSpeed NGINX Extras.

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_markdown_filter_module.so;

Este documento descreve nginx-module-markdown v1.0.0 lançado em 15 de fevereiro de 2026.

Um módulo NGINX que transforma arquivos Markdown em HTML em tempo real com suporte para YAML front matter, extensões GFM e templates personalizáveis.

Construído sobre cmark-gfm (GitHub Flavored Markdown), este módulo permite servir documentação Markdown diretamente do NGINX com suporte completo para SEO através da extração dinâmica de metadados.

Recursos

Recurso	Descrição
Conversão em tempo real	Sirva arquivos `.md` como HTML sem pré-processamento
YAML front matter	Extraia metadados para títulos dinâmicos, descrições e tags SEO
Sistema de templates	Envolva o conteúdo em templates HTML personalizados com substituição de placeholders
Extensões GFM	Tabelas, tachado, listas de tarefas, autolinks e filtragem de tags
Zero dependências em tempo de execução	Linkado estaticamente, sem serviços externos necessários
Suporte a proxy	Funciona com arquivos markdown upstream, não apenas arquivos locais

Início Rápido

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

Referência de Diretivas

markdown_filter


Sintaxe	`markdown_filter on \\| off;`
Padrão	`off`
Contexto	`location`

Habilita ou desabilita a conversão de Markdown para HTML.

markdown_template


Sintaxe	`markdown_template <caminho>;`
Padrão	—
Contexto	`location`

Caminho para um arquivo de template HTML. Use o placeholder {{content}} para inserir o Markdown renderizado.

markdown_front_matter


Sintaxe	`markdown_front_matter on \\| off;`
Padrão	`off`
Contexto	`location`

Analisa o YAML front matter de arquivos Markdown para habilitar a substituição de placeholders de template.

markdown_unsafe


Sintaxe	`markdown_unsafe on \\| off;`
Padrão	`off`
Contexto	`location`

Permite a passagem de HTML bruto no conteúdo Markdown. Use com cautela em entradas não confiáveis.

markdown_gfm_tagfilter


Sintaxe	`markdown_gfm_tagfilter on \\| off;`
Padrão	`off`
Contexto	`location`

Filtra tags HTML perigosas (<script>, <iframe>, <style>, etc.) da saída.

markdown_gfm_tasklist


Sintaxe	`markdown_gfm_tasklist on \\| off;`
Padrão	`off`
Contexto	`location`

Habilita caixas de seleção de listas de tarefas no estilo GitHub: - [ ] e - [x].

markdown_gfm_strikethrough


Sintaxe	`markdown_gfm_strikethrough on \\| off;`
Padrão	`off`
Contexto	`location`

Habilita a sintaxe ~~strikethrough~~.

markdown_gfm_autolink


Sintaxe	`markdown_gfm_autolink on \\| off;`
Padrão	`off`
Contexto	`location`

Converte automaticamente URLs e endereços de e-mail em links clicáveis.

Sistema de Templates

Templates envolvem o Markdown renderizado em HTML personalizado. Use {{content}} para marcar onde o Markdown convertido aparece:

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

YAML Front Matter

Habilite markdown_front_matter para extrair metadados de arquivos Markdown e substituir placeholders de template dinamicamente. Essencial para otimização de SEO.

Exemplo de Arquivo Markdown

---
title: Guia de Introdução
meta:
  description: Aprenda como instalar e configurar o módulo
  keywords: nginx, markdown, documentação
  robots: index, follow
author: Equipe de Documentação
---

## Introdução

Bem-vindo à documentação.

Exemplo de Template

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

Recursos do Front Matter

Chaves aninhadas — Acesse com notação de ponto: {{meta.description}}
Tratamento de aspas — Aspas ao redor são automaticamente removidas
Fallback gracioso — Valores ausentes são renderizados como strings vazias
Compatível com versões anteriores — Arquivos sem front matter funcionam normalmente

Extensões GFM

Quando construído com cmark-gfm (padrão nos pacotes GetPageSpeed), estas extensões estão disponíveis:

Extensão	Diretiva	Exemplo
Tabelas	Sempre habilitado	`\| A \| B \|`
Tachado	`markdown_gfm_strikethrough on`	`~~deletado~~`
Listas de Tarefas	`markdown_gfm_tasklist on`	`- [x] Feito`
Autolinks	`markdown_gfm_autolink on`	`https://example.com`
Filtro de Tags	`markdown_gfm_tagfilter on`	Sanitiza `<script>`, `<iframe>`, etc.

Exemplos de Configurações

Site de Documentação

Sirva documentação Markdown com metadados SEO adequados:

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 com CMS Upstream

Processar Markdown de um CMS sem cabeça:

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

Wiki com Conteúdo de Usuário

Permitir conteúdo contribuído por usuários com sanitização de HTML:

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # Permitir HTML, mas filtrar tags perigosas
    markdown_template /etc/nginx/templates/wiki.html;
}

Configuração 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;
}