mdToPDF

This project is open-sourced on github and gitlink (China-network friendly).

A Chinese Markdown-to-PDF project based on Pandoc + LuaLaTeX.

This project is derived from and heavily adapted for Chinese from Eisvogel.

It supports a graded six-level heading scale, Chinese fake-bold / fake-italic, colorful emoji and special symbols, GitHub-style admonitions, code highlighting, tables and math formulas — ideal for turning course notes, lab reports and documents into polished, good-looking PDFs.

Preview

Features

• Graded six-level heading scale: # to ###### step down in size, with a clear hierarchy.
• Chinese bold / italic: AutoFakeBold / AutoFakeSlant allow synthesizing bold and italic even for fonts that lack them.
• Colorful emoji and special symbols: uses lualatex + mainfontfallback to render Unicode characters and colorful emojis.
• GitHub-style admonitions: the alerts.lua filter renders five colored callout blocks — note / tip / important / warning / caution.
• Mermaid diagrams: the diagram.lua filter calls mermaid-cli to render ```mermaid code blocks into vector images embedded in the PDF.
• Code highlighting, tables, math formulas: native Pandoc support, with the idiomatic syntax-highlighting style.
• Title page / TOC / colored links: controlled via YAML Front Matter switches.

Directory Structure

mdToPDF/
├── src/                    # Holds the Markdown source files and build scripts
│   ├── example.md          # Example Markdown file
│   ├── build_windows.ps1   # Windows build script
│   └── build_linux.sh      # Linux / macOS build script
├── build/                  # Build output directory; PDFs are auto-generated by the build scripts
├── preview/                # Sample build output and its preview images
├── resources/              # Templates and resources
│   ├── eisvogel.latex      # LaTeX template
│   ├── eisvogel.beamer     # beamer template
│   ├── alerts.lua          # GitHub-style admonition Lua filter
│   ├── diagram.lua         # Lua filter for Mermaid and other diagrams
│   └── background.pdf      # Title-page / page background image
├── package.json            # Node dependency manifest (local mermaid-cli)
└── LICENSE.md              # PolyForm Noncommercial License 1.0.0

Requirements

Component	Version / Notes
Pandoc	refer to one of my blog post for the installation
TeX Live	refer to my another blog post for the installation
Node.js (with npm)	only required for rendering Mermaid diagrams. Run npm install in the project root to locally install @mermaid-js/mermaid-cli (its Puppeteer dependency automatically downloads Chromium on first run)
Fonts	SimSun, Source Sans 3, Noto Color Emoji, FreeSans, DejaVu Sans

Font notes: SimSun is used for Chinese body text; Source Sans 3 is the Latin main font; Noto Color Emoji / FreeSans / DejaVu Sans form the emoji and special-symbol fallback chain.

Linux / macOS notes

• Pandoc version: --syntax-highlighting idiomatic requires Pandoc 3.6 or newer. build_linux.sh detects the installed version automatically and falls back to --highlight-style (and to the default style when idiomatic is unavailable) on older releases.

• Fonts (Ubuntu / Debian example):

  sudo apt install fonts-noto-cjk fonts-noto-color-emoji \
                   fonts-freefont-ttf fonts-dejavu-core

  Source Sans 3 is not packaged in the official apt repositories. Download the TTFs from the Adobe repository, place them under ~/.local/share/fonts/ (no root required) and run fc-cache -f to refresh the font cache. SimSun is a proprietary Windows font; on Linux without a license you can replace both fonts through environment variables:

  CJK_FONT="Noto Serif CJK SC" MAIN_FONT="Noto Sans" bash src/build_linux.sh

• Mermaid in containers / CI: some Linux distributions (e.g. Ubuntu 23.10+) and containers disallow unprivileged user namespaces, so the Chromium sandbox cannot start. The script probes this automatically and switches to an --no-sandbox compatibility mode (only use it for rendering your own trusted diagrams) — no manual configuration required.

Usage

One-shot build

Put your Markdown files into src/, then run the build script.

Windows (PowerShell):

.\src\build_windows.ps1

Linux / macOS (bash):

bash src/build_linux.sh

# or make it executable and run it directly
chmod +x src/build_linux.sh
./src/build_linux.sh

The script iterates over every *.md in src/ and produces a matching build/<name>.pdf for each.

Build script parameters:

• Input format: markdown+alerts
• Template: resources/latex/eisvogel.latex
• Engine: lualatex
• Filters: resources/alerts.lua (admonitions) and resources/diagram.lua (Mermaid diagrams)
• Syntax highlighting: idiomatic
• Chinese main font: SimSun; Latin main font: Source Sans 3
• emoji / symbol fallback chain: Noto Color Emoji → FreeSans → DejaVu Sans

In addition to the parameters above, build_linux.sh adds the following Linux-specific logic:

• Font preflight: every required font is checked with fc-list before building; the script aborts with a clear message and substitution suggestions when a font is missing (skip with SKIP_FONT_CHECK=1).
• Overridable fonts: the defaults can be changed with environment variables — CJK_FONT (Chinese main font, default SimSun), MAIN_FONT (Latin main font, default Source Sans 3), HIGHLIGHT_STYLE (highlight style, default idiomatic).
• Mermaid sandbox auto-detection: it probes whether the Chromium sandbox works and generates an --no-sandbox wrapper under build/ when it does not — no manual intervention needed.

Single-file build

pandoc .\src\example.md -o .\build\example.pdf `
  --from markdown+alerts `
  --template ".\resources\latex\eisvogel.latex" `
  --syntax-highlighting idiomatic `
  --pdf-engine "lualatex" `
  -V CJKmainfont="SimSun" `
  -V mainfont="Source Sans 3" `
  -V mainfontfallback="Noto Color Emoji:mode=harf" `
  -V mainfontfallback="FreeSans:mode=harf" `
  -V mainfontfallback="DejaVu Sans:mode=harf" `
  --lua-filter ".\resources\alerts.lua" `
  --lua-filter ".\resources\diagram.lua"

[!NOTE] If your document contains Mermaid diagrams, the single-file command needs the filter to find mermaid-cli first: $env:MERMAID_BIN = ".\node_modules\.bin\mmdc.cmd" (no manual setup is needed when running build_windows.ps1, which already sets it).

The equivalent bash command on Linux / macOS (note mmdc without the .cmd suffix):

export MERMAID_BIN="$(pwd)/node_modules/.bin/mmdc"
pandoc src/example.md -o build/example.pdf \
  --from markdown+alerts \
  --template resources/eisvogel.latex \
  --syntax-highlighting idiomatic \
  --pdf-engine lualatex \
  -V CJKmainfont="SimSun" \
  -V mainfont="Source Sans 3" \
  -V mainfontfallback="Noto Color Emoji:mode=harf" \
  -V mainfontfallback="FreeSans:mode=harf" \
  -V mainfontfallback="DejaVu Sans:mode=harf" \
  --lua-filter resources/alerts.lua \
  --lua-filter resources/diagram.lua

[!NOTE] Pandoc older than 3.6 has no --syntax-highlighting flag — replace --syntax-highlighting idiomatic with --highlight-style=tango (or drop the flag to use the default). You do not need to worry about this when running build_linux.sh, which handles the difference automatically.

Writing Markdown

Front Matter

Set the title, author, table of contents, title page, etc. with a YAML block at the top of your .md file:

---
title: "标题"
author: [你的名字]
date: "2026-09-12"
subject: "Markdown"
keywords: [关键词, markdown]
subtitle: "副标题"
titlepage: true            # Enable the cover page
titlepage-rule-color: "00727c"
titlepage-background: "<absolute path>"   # Title-page background
page-background: "<absolute path>"        # Body-page background
colorlinks: true          # Color hyperlinks
block-headings: true      # Headings occupy their own line
toc: true                 # Table of contents
toc-own-page: true        # TOC on its own page
---

[!NOTE] During testing we found that using an absolute path for the background prevents a successful build. For any other questions, feel free to discuss them in the Issues section.

GitHub-style admonitions

Use the GitHub-style > [!TYPE] blockquote syntax; alerts.lua renders it as a colored block:

> [!NOTE]
> Explanation

[!NOTE] Explanation

> [!TIP]
> Tip

[!TIP] Tip

> [!IMPORTANT]
> Important

[!IMPORTANT] Important

> [!WARNING]
> Warning

[!WARNING] Warning

> [!CAUTION]
> Danger

[!CAUTION] Danger

Mermaid diagrams

Use a code block with the mermaid language tag; the diagram.lua filter calls mermaid-cli to render the diagram as a vector PDF embedded in the document. Flowcharts, sequence diagrams, state diagrams, Gantt charts and every other diagram type supported by Mermaid work:

```mermaid
stateDiagram-v2
    [*] --> NOMINAL
    NOMINAL --> EMERGENCY: critical fault
    EMERGENCY --> [*]
```

Install the dependency before first use (Node.js / npm required):

npm install

The dependency is installed locally inside the project (node_modules/), nothing is written to the global environment. mermaid-cli depends on Puppeteer, which automatically downloads a Chromium build into the user cache directory on its first run.

Customization

• Change the template: edit resources/latex/eisvogel.latex (heading sizes, fonts, colors, headers/footers, etc.).
• Change GitHub-style admonition styles: edit resources/alerts.lua (colors, borders, title text).
• Change diagram rendering: edit resources/diagram.lua; besides mermaid it also ships with plantuml, graphviz, tikz and d2 engines — install the corresponding executable and use a code block with the matching language tag.
• Change the build flow: edit src/build_windows.ps1 on Windows or src/build_linux.sh on Linux / macOS.
• Reference upstream: for other questions you can also refer to the upstream project Eisvogel.

LICENSE

This project is released under the PolyForm Noncommercial License 1.0.0.

Required Notice: Copyright 2026 jianyuewushuang jianyuewushuang@163.com

Noncommercial use is free to use, modify and distribute; for commercial use, please contact the author.