markdown-to-pdf-agent-skill

markdown-to-pdf

An agent skill that turns Markdown files — including Obsidian notes — into polished, print-ready PDFs.

It drives a LaTeX-free pipeline: Pandoc converts the content and WeasyPrint handles the layout (pagination, headers/footers, cover page, table of contents). Everything ships inside the skill — template, CSS, Lua filters and a self-contained Docker image — so there is no external toolchain to assemble.

note.md ──[Pandoc + Lua filters]──▶ HTML ──[WeasyPrint + CSS]──▶ PDF

The skill stays agnostic: plain Markdown converts cleanly, and Obsidian-specific features are only applied when the matching syntax is present.

Features

• Cover page driven by YAML frontmatter (title, subtitle, author, date, logo, accent color).
• Table of contents with page numbers and leader dots.
• Running headers/footers with title, date, author and page numbers.
• Obsidian callouts (> [!note], [!warning], [!tip]…), including nested ones.
• Image embeds ![[image.png|width]] with automatic path resolution (no --resource-path needed — the image is found by name anywhere under the vault).
• Wikilinks [[note]] / [[note|alias]] rendered as clean text (no dead links).
• Figures with captions, styled tables, code blocks, blockquotes.
• A library of bundled fonts (system + Google/open-source: Inter, Roboto, Montserrat, Merriweather, JetBrains Mono…) ready to use in custom templates.

Requirements

• Docker — the whole pipeline (Pandoc + WeasyPrint
  • fonts) runs inside a self-contained image, so Docker is the only system dependency. No LaTeX, no Pandoc, no WeasyPrint to install on the host.
• An agent that supports skills (e.g. Claude Code).

The first generation builds the Docker image (a few minutes, one-time). Subsequent runs reuse it instantly.

Installation

Install the skill with skills:

npx skills install vlebert/markdown-to-pdf-agent-skill

This pulls the skill into your agent's skills directory. From then on, just ask your agent to export a Markdown file to PDF and the skill triggers automatically.

You can also clone the repository directly into your skills folder if you prefer to manage it manually.

How it works

1. Build/check the Docker image. Before generating, the skill ensures the markdown-to-pdf:latest image exists (scripts/build-image.sh is idempotent — it only builds when the image is missing).
2. Prepare the frontmatter. The agent inspects the note's YAML frontmatter and fills in useful keys (title, author, date, cover page and TOC options), asking you when something is ambiguous.
3. Pick the Lua filters. Only the transformations matching the syntax actually present in the note are applied (callouts, image embeds, wikilinks…), keeping plain Markdown untouched.
4. Generate. Pandoc + WeasyPrint run in the container and write the PDF next to the source note (or in the vault's attachments folder for Obsidian).
5. Offer adjustments. Once the PDF is produced, the agent lists the available levers (heading numbering, TOC depth, cover page, template, metadata) and regenerates on request.

Custom templates

A template is a visual identity — a template.html + style.css pair under assets/templates/. You can ask the agent to create one (new colors, fonts, margins, cover layout); the Lua filters are shared and never duplicated. The agent also records the template choice in your project's CLAUDE.md/AGENTS.md so future sessions reuse it automatically.

Repository layout

The skill itself lives under skills/markdown-to-pdf/ (the skills/<name>/ layout expected by npx skills — a root-level SKILL.md would install without its bundled assets).

License

See repository for license details.