markdown-to-pdf

Markdown to PDF Skill

Convert Markdown documents into professional Apple-design-style PDF whitepapers.

Core Features

Professional Typesetting: Book-level typesetting quality, automatically handles pagination, widows and orphans
Apple Design: SF font system, modern minimalist style, professional color scheme
Complete Table of Contents: Automatically extracts chapter structure, two-column layout, clickable navigation
Perfect Markdown Support: Code blocks, tables, quotes, lists, and more all rendered correctly

Usage

Basic Usage

# 转换单个文件
python scripts/convert.py input.md

Specify the output filename

python scripts/convert.py input.md -o "My Whitepaper.pdf"

Customize title and author

python scripts/convert.py input.md --title "Technical Whitepaper" --author "花叔"


### Markdown 文档要求

你的 Markdown 文档应该遵循以下结构：

```markdown
# 文档标题

## 1. 第一章
### 1.1 第一节
### 1.2 第二节

## 2. 第二章
### 2.1 第一节

Key Rules：

Main chapters:## 1. 标题(number + dot + space + title)
Subchapters:### 1.1 标题(number.number + space + title)
Only this way can the table of contents be extracted correctly

Design Features

Cover Design

Light gray gradient background
Large title: 64pt, clean and modern
Subtitle and metadata

Table of Contents Design

Two-column layout, displayed on a single page
Main chapters in bold, subchapters indented
Clickable jump to the corresponding chapter

Body Typesetting

SF font family (Apple design language)
Line height 1.7, comfortable reading
Chapters automatically paginated
Widow and orphan control

Code Blocks

Light gray background + thin border
8px rounded corners
SF Mono monospace font
Automatically avoids pagination

Tables

Clear grid lines
Light gray header
Automatically preserves the header (when long tables are paginated)

Configuration Options

If you need custom styles, you can modify the CSS variables in scripts/convert.py :

# 主色调
PRIMARY_COLOR = '#06c'      # 苹果蓝
TEXT_COLOR = '#1d1d1f'      # 主文本黑色
GRAY_COLOR = '#86868b'      # 浅灰色

# 字体大小
COVER_TITLE_SIZE = '64pt'
H2_SIZE = '22pt'
H3_SIZE = '17pt'
BODY_SIZE = '11pt'

FAQ

Q: Why is the table of contents empty?

A: Make sure your Markdown uses the correct chapter format:

## 1. 标题 instead of ## 标题
### 1.1 标题 instead of ### 标题

Q: Code blocks are not displayed correctly?

A: Make sure to wrap them with three backticks:

```python
def hello():
    print("Hello")
```

Q: The table format is messed up?

A: Use standard Markdown table syntax:

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

Q: How do I change the font?

A: Edit the CSS in scripts/convert.py , modify the font-family property.

Q: The generated PDF is too large?

A: Check whether there are a large number of images, and consider compressing the images or using external links.

Dependency Installation

Python dependencies need to be installed for first-time use:

pip3 install markdown2 weasyprint

If you encounter WeasyPrint installation issues (macOS):

brew install pango
pip3 install weasyprint

Examples

Generate technical documentation

python scripts/convert.py tech-guide.md -o "技术指南.pdf"

Generate a whitepaper

python scripts/convert.py whitepaper.md --title "产品白皮书" --author "团队"

Script Description

scripts/convert.py - Main conversion script
scripts/styles.css - CSS style definitions (embedded in the script)
templates/cover.html - Cover template (embedded in the script)

Technical Implementation

This Skill uses:

markdown2: Markdown parsing (supports extended syntax)
WeasyPrint: HTML to PDF conversion (supports CSS3)
Apple Design System: SF fonts, professional color schemes, modern typography

Changelog

v1.0 (2025-12-24)

Initial version
Supports full Markdown syntax
Apple design style
Automatic table of contents generation
Book-level typographic quality