markdown: Markdown-to-html NGINX 模块

需要 GetPageSpeed NGINX Extras 订阅的 Pro 计划（或更高版本）。

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

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

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用该模块：

load_module modules/ngx_markdown_filter_module.so;

本文档描述了 nginx-module-markdown v1.0.0，于 2026 年 2 月 15 日发布。

一个 NGINX 模块，可以动态将 Markdown 文件转换为 HTML，支持 YAML 前置信息、GFM 扩展和可自定义模板。

基于 cmark-gfm（GitHub 风格的 Markdown），该模块使得可以直接从 NGINX 提供 Markdown 文档，并通过动态元数据提取提供完整的 SEO 支持。

特性

特性	描述
动态转换	无需预处理即可将 `.md` 文件作为 HTML 提供
YAML 前置信息	提取元数据以动态生成标题、描述和 SEO 标签
模板系统	在自定义 HTML 模板中包装内容并进行占位符替换
GFM 扩展	表格、删除线、任务列表、自动链接和标签过滤
零运行时依赖	静态链接，无需外部服务
代理支持	支持上游 Markdown 文件，而不仅仅是本地文件

快速开始

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

指令参考

markdown_filter


语法	`markdown_filter on \\| off;`
默认	`off`
上下文	`location`

启用或禁用 Markdown 到 HTML 的转换。

markdown_template


语法	`markdown_template <path>;`
默认	—
上下文	`location`

HTML 模板文件的路径。使用 {{content}} 占位符插入渲染的 Markdown。

markdown_front_matter


语法	`markdown_front_matter on \\| off;`
默认	`off`
上下文	`location`

从 Markdown 文件中解析 YAML 前置信息，以启用模板占位符替换。

markdown_unsafe


语法	`markdown_unsafe on \\| off;`
默认	`off`
上下文	`location`

允许在 Markdown 内容中直接通过原始 HTML。在不受信任的输入上使用时请谨慎。

markdown_gfm_tagfilter


语法	`markdown_gfm_tagfilter on \\| off;`
默认	`off`
上下文	`location`

从输出中过滤危险的 HTML 标签（<script>、<iframe>、<style> 等）。

markdown_gfm_tasklist


语法	`markdown_gfm_tasklist on \\| off;`
默认	`off`
上下文	`location`

启用 GitHub 风格的任务列表复选框：- [ ] 和 - [x]。

markdown_gfm_strikethrough


语法	`markdown_gfm_strikethrough on \\| off;`
默认	`off`
上下文	`location`

启用 ~~strikethrough~~ 语法。

markdown_gfm_autolink


语法	`markdown_gfm_autolink on \\| off;`
默认	`off`
上下文	`location`

自动将裸露的 URL 和电子邮件地址转换为可点击的链接。

模板系统

模板将渲染的 Markdown 包裹在自定义 HTML 中。使用 {{content}} 标记转换后的 Markdown 出现的位置：

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

YAML 前置信息

启用 markdown_front_matter 从 Markdown 文件中提取元数据，并动态替换模板占位符。这对于 SEO 优化至关重要。

示例 Markdown 文件

---
title: Getting Started Guide
meta:
  description: Learn how to install and configure the module
  keywords: nginx, markdown, documentation
  robots: index, follow
author: Documentation Team
---

## Getting Started

Welcome to the documentation.

示例模板

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

前置信息特性

嵌套键 — 使用点表示法访问：{{meta.description}}
引号处理 — 周围的引号会自动去掉
优雅回退 — 缺失的值呈现为空字符串
向后兼容 — 没有前置信息的文件正常工作

GFM 扩展

使用 cmark-gfm 构建时（在 GetPageSpeed 包中默认），可用以下扩展：

扩展	指令	示例
表格	始终启用	`\| A \| B \|`
删除线	`markdown_gfm_strikethrough on`	`~~deleted~~`
任务列表	`markdown_gfm_tasklist on`	`- [x] Done`
自动链接	`markdown_gfm_autolink on`	`https://example.com`
标签过滤	`markdown_gfm_tagfilter on`	清理 `<script>`、`<iframe>` 等。

示例配置

文档网站

提供带有适当 SEO 元数据的 Markdown 文档：

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

使用上游 CMS 的博客

处理来自无头 CMS 的 Markdown：

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

用户内容的维基

允许用户贡献内容并进行 HTML 清理：

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # 允许 HTML，但过滤危险标签
    markdown_template /etc/nginx/templates/wiki.html;
}

完整功能配置

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