Markdown Professional PDF Converter

The Problem

Markdown is often readable in a browser, but it is not always stable for printing, archiving, or formal delivery. Issues such as A4 margins, page numbers, Chinese typography, code highlighting, table pagination, and link rendering can affect the final appearance. mdtopdf targets this document-output use case by converting Markdown into a consistent PDF instead of relying on browser print behavior or ad hoc styling.

How It Works

It is built on md2pdf and WeasyPrint, using @scripts/convert.py to read a Markdown file and apply @assets/markdown.css. The default layout includes A4 pages, 25mm/20mm margins, footer page numbers, serif body text, and sans-serif headings. Code blocks use a monospace stack with Pygments GitHub-style highlighting; tables get borders, alternating row colors, and repeating headers across pages; blockquotes, links, and page breaks are also print-aware. If the Markdown does not start with a heading, --title can inject one. Relative image paths depend on base_url, which the conversion script sets to the Markdown file's parent directory.
It also supports customizing the output: you can pass your own CSS or call the Python API directly to adjust styles, titles, fonts, and pagination behavior. By default, it enables extensions such as GFM tables, pymdownx.superfences, footnotes, and smart punctuation, making it suitable for technical documents with tables, code blocks, footnotes, and Chinese text.

Limits and Notes

This skill is best for producing formal PDFs from Markdown, not for JavaScript-rendered pages, interactive components, or complex web layouts. Missing Chinese fonts can produce square glyphs, so the environment should provide CJK fonts. Missing system libraries required by WeasyPrint can prevent it from running, and the documented str | None case requires Python 3.10+. When customizing styles, extend or override the default CSS and confirm that image paths resolve, to avoid blank pages or missing images.