markdown: Модуль NGINX для преобразования Markdown в HTML

Требуется план Pro (или выше) подписки GetPageSpeed NGINX Extras.

Установка

Вы можете установить этот модуль в любой дистрибутив на базе 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, выпущенный 15 февраля 2026 года.

Модуль NGINX, который преобразует файлы Markdown в HTML на лету с поддержкой YAML front matter, расширений GFM и настраиваемых шаблонов.

Созданный на основе cmark-gfm (GitHub Flavored Markdown), этот модуль позволяет обслуживать документацию Markdown непосредственно из NGINX с полной поддержкой SEO через динамическое извлечение метаданных.

Особенности

Особенность	Описание
Преобразование на лету	Обслуживайте `.md` файлы как HTML без предварительной обработки
YAML front matter	Извлечение метаданных для динамических заголовков, описаний и 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`

Парсинг YAML front matter из файлов Markdown для включения замены плейсхолдеров в шаблонах.

markdown_unsafe


Синтаксис	`markdown_unsafe on \\| off;`
По умолчанию	`off`
Контекст	`location`

Разрешить прямую передачу HTML в контенте Markdown. Используйте с осторожностью для ненадежного ввода.

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>Документация</title>
    <link rel="stylesheet" href="/css/docs.css">
</head>
<body>
    <main>{{content}}</main>
</body>
</html>

YAML Front Matter

Включите markdown_front_matter, чтобы извлекать метаданные из файлов Markdown и динамически заменять плейсхолдеры шаблона. Это необходимо для оптимизации SEO.

Пример файла Markdown

---
title: Руководство по началу работы
meta:
  description: Узнайте, как установить и настроить модуль
  keywords: nginx, markdown, документация
  robots: index, follow
author: Команда документации
---

## Начало работы

Добро пожаловать в документацию.

Пример шаблона

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

Особенности front matter

Вложенные ключи — Доступ через точечную нотацию: {{meta.description}}
Обработка кавычек — Окружающие кавычки автоматически удаляются
Корректный запасной вариант — Отсутствующие значения отображаются как пустые строки
Обратная совместимость — Файлы без front matter работают нормально

Расширения GFM

Когда модуль собран с использованием cmark-gfm (по умолчанию в пакетах GetPageSpeed), доступны следующие расширения:

Расширение	Директива	Пример
Таблицы	Всегда включены	`\| A \| B \|`
Зачеркивание	`markdown_gfm_strikethrough on`	`~~удалено~~`
Списки задач	`markdown_gfm_tasklist on`	`- [x] Сделано`
Автоссылки	`markdown_gfm_autolink on`	`https://example.com`
Фильтр тегов	`markdown_gfm_tagfilter on`	Очищает `<script>`, `<iframe>`, и т.д.

Примеры конфигураций

Сайт документации

Обслуживание документации Markdown с правильными метаданными SEO:

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

Обработка Markdown из безголовой CMS:

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