markdown: Markdown-to-html NGINX module

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-markdown provided by the GetPageSpeed Extras repository.

Configure the APT repository as described in APT repository setup.
Install the module:

sudo apt-get update
sudo apt-get install nginx-module-markdown

Warning

This module is not yet published as nginx-module-markdown in the APT repositories. Stay tuned, or email [email protected] to request it.

An NGINX module that transforms Markdown files to HTML on-the-fly with support for YAML front matter, GFM extensions, and customizable templates.

Built on cmark-gfm (GitHub Flavored Markdown), this module enables serving Markdown documentation directly from NGINX with full SEO support through dynamic metadata extraction.

Features

On-the-fly conversion - Serve .md files as HTML without preprocessing
YAML front matter - Extract metadata for dynamic titles, descriptions, and SEO tags
Template system - Wrap content in custom HTML templates with placeholder substitution
GFM extensions - Tables, strikethrough, task lists, autolinks, and tag filtering
Zero dependencies at runtime - Statically linked, no external services required
Proxy support - Works with upstream markdown files, not just local files

RHEL/CentOS/AlmaLinux/Rocky Linux

sudo yum install nginx-module-markdown-filter

Debian/Ubuntu

sudo apt install nginx-module-markdown-filter

Load the module in your `nginx.conf`:

```nginx
load_module modules/ngx_markdown_filter_module.so;

Quick Start

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

Directives

Directive	Default	Context	Description
`markdown_filter`	`off`	location	Enable Markdown to HTML conversion
`markdown_template`	-	location	Path to HTML template file
`markdown_front_matter`	`off`	location	Parse YAML front matter for placeholders
`markdown_unsafe`	`off`	location	Allow raw HTML passthrough
`markdown_gfm_tagfilter`	`off`	location	Filter dangerous HTML tags
`markdown_gfm_tasklist`	`off`	location	Enable `- [ ]` / `- [x]` checkboxes
`markdown_gfm_strikethrough`	`off`	location	Enable `~~strikethrough~~` syntax
`markdown_gfm_autolink`	`off`	location	Auto-link bare URLs and emails

Template System

Templates wrap rendered Markdown in custom HTML. Use {{content}} to mark where the converted Markdown appears:

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

Enable markdown_front_matter to extract metadata from Markdown files and substitute template placeholders dynamically. This is essential for SEO optimization.

Configuration

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

Markdown File

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

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>

Front Matter Features

Nested keys - Access with dot notation: {{meta.description}}
Quote handling - Surrounding quotes are automatically stripped
Graceful fallback - Missing values render as empty strings
Backward compatible - Files without front matter work normally

GFM Extensions

When built with cmark-gfm (default in GetPageSpeed packages), these extensions are available:

Extension	Directive	Example
Tables	Always enabled	`\\| A \\| B \\|`
Strikethrough	`markdown_gfm_strikethrough on`	`~~deleted~~`
Task Lists	`markdown_gfm_tasklist on`	`- [x] Done`
Autolinks	`markdown_gfm_autolink on`	`https://example.com`
Tag Filter	`markdown_gfm_tagfilter on`	Sanitizes `<script>`, `<iframe>`, etc.

Full-Featured Configuration

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

Use Cases

Documentation Sites

Serve Markdown documentation with proper SEO metadata:

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

Blog with Upstream CMS

Process Markdown from a headless CMS:

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

Wiki-Style Pages

Allow user-contributed content with HTML sanitization:

location /wiki/ {
    markdown_filter on;
    markdown_unsafe on;
    markdown_gfm_tagfilter on;  # Allow HTML but filter dangerous tags
    markdown_template /etc/nginx/templates/wiki.html;
}

RHEL/CentOS/Fedora

dnf install cmark-gfm-devel

Debian/Ubuntu

apt install libcmark-gfm-dev libcmark-gfm-extensions-dev ```

Without GFM Extensions

For standard CommonMark without GitHub extensions:

```bash