Skip to content

markdown: Markdown-to-html NGINX module

Requires the Pro plan (or higher) of the GetPageSpeed NGINX Extras subscription.

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 7, 8, 9 and 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 and Amazon Linux 2023
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

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_markdown_filter_module.so;

This document describes nginx-module-markdown v1.0.0 released on Feb 15 2026.

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

Feature Description
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 runtime deps Statically linked, no external services required
Proxy support Works with upstream markdown files, not just local files

Quick Start

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

Directives Reference

markdown_filter
Syntax markdown_filter on \| off;
Default off
Context location

Enables or disables Markdown to HTML conversion.

markdown_template
Syntax markdown_template <path>;
Default —
Context location

Path to an HTML template file. Use {{content}} placeholder to insert rendered Markdown.

markdown_front_matter
Syntax markdown_front_matter on \| off;
Default off
Context location

Parse YAML front matter from Markdown files to enable template placeholder substitution.

markdown_unsafe
Syntax markdown_unsafe on \| off;
Default off
Context location

Allow raw HTML passthrough in Markdown content. Use with caution on untrusted input.

markdown_gfm_tagfilter
Syntax markdown_gfm_tagfilter on \| off;
Default off
Context location

Filter dangerous HTML tags (<script>, <iframe>, <style>, etc.) from output.

markdown_gfm_tasklist
Syntax markdown_gfm_tasklist on \| off;
Default off
Context location

Enable GitHub-style task list checkboxes: - [ ] and - [x].

markdown_gfm_strikethrough
Syntax markdown_gfm_strikethrough on \| off;
Default off
Context location

Enable ~~strikethrough~~ syntax.
Syntax markdown_gfm_autolink on \| off;
Default off
Context location

Automatically convert bare URLs and email addresses into clickable links.

Template System

Templates wrap rendered Markdown in custom HTML. Use {{content}} to mark where 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. Essential for SEO optimization.

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

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

Example Configurations

Documentation Site

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;
    markdown_gfm_autolink 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 with User Content

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

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