SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmarkdown-to-pdf

markdown-to-pdf

Office & productivity

View repository

Updated 10-16 08:01

About this skill

Markdown to PDF Skill (v2.0)

Convert Markdown documents into professional Apple-design-style PDF white papers.

Version Update

v2.0 (2025-01-30)

Major Improvements:

  • ✅ Use pdfkit + wkhtmltopdf instead of WeasyPrint
  • ✅ Remove pango dependency, simpler installation
  • ✅ Support WebP image format
  • ✅ Automatically handle images without extensions
  • ✅ Add a complete image processing toolchain
  • ✅ Provide a one-click workflow

Dependency Changes:

# 旧版本 (v1.0)
pip3 install markdown2 weasyprint
brew install pango  # 复杂

# 新版本 (v2.0)
pip3 install markdown pdfkit Pillow
brew install wkhtmltopdf  # 简单

Core Features

  1. Professional Typesetting: Book-level typesetting quality, automatically handles pagination, widows, and orphans
  2. Apple Design: SF font system, modern minimalist style, professional color scheme
  3. Complete Table of Contents: Automatically extracts chapter structure, two-column layout, clickable navigation
  4. Perfect Markdown Support: Code blocks, tables, quotes, lists, etc. are all rendered correctly
  5. Image Processing: Automatically detects and converts WebP images, handles images without extensions
  6. One-Click Workflow: A complete automated process from image processing to PDF generation

Usage

Method 1: Basic Conversion

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

# 指定输出文件名
python scripts/convert.py input.md -o "我的白皮书.pdf"

# 自定义标题和作者
python scripts/convert.py input.md --title "技术白皮书" --author "花叔"

Method 2: Complete Workflow (recommended)

# 一键执行: 图片处理 + PDF 生成
python scripts/workflow.py input.md

# 跳过图片处理
python scripts/workflow.py input.md --skip-images

# 完整自定义
python scripts/workflow.py input.md \
  --title "技术白皮书" \
  --author "团队" \
  -o "output.pdf"

Method 3: Step-by-Step Execution

# 步骤 1: 分析图片格式
python scripts/analyze_images.py

# 步骤 2: 转换 WebP 图片
python scripts/batch_convert_images.py

# 步骤 3: 更新 Markdown 引用
python scripts/update_markdown_refs.py

# 步骤 4: 生成 PDF
python scripts/convert.py input.md

Markdown Document Requirements

Your Markdown document should follow the structure below:

# 文档标题

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

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

Key Rules:

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

Tool Description

convert.py - Core Conversion Tool

Converts Markdown to PDF, supporting:

  • Metadata extraction (title, author, date, etc.)
  • Table of contents generation (two-column layout)
  • Image path handling (absolute paths + extension completion)
  • Apple design style CSS

analyze_images.py - Image Format Analysis

Detects the actual image format:

  • Detects the true format via Magic Bytes
  • Identifies WebP without an extension
  • Identifies WebP with an incorrect extension
  • Generates a conversion plan report

batch_convert_images.py - Batch Image Conversion

Batch converts WebP to PNG:

  • Executes according to the conversion plan
  • Automatically deletes the original WebP files
  • Generates a filename mapping table
  • Generates a conversion report

update_markdown_refs.py - Reference Update

Updates image references in Markdown:

  • Supports HTML img tags
  • Supports Markdown image syntax
  • Performs batch replacement according to the mapping table
  • Generates an update report

workflow.py - Complete Workflow

Executes all steps with one click:

  • Automatically analyzes images
  • Automatically converts formats
  • Automatically updates references
  • Automatically generates PDF

Design Features

Cover Design

  • Light gray gradient background
  • Large title: 64pt, clean and modern
  • Subtitle and meta information

Table of Contents Design

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

Body Typography

  • SF font family (Apple design language)
  • Line height 1.7, comfortable reading
  • Automatic chapter pagination
  • Widow and orphan control

Code Blocks

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

Tables

  • Clear grid lines
  • Light gray header
  • Automatically repeats the header (when long tables span pages)

Dependency Installation

Python Dependencies

pip3 install markdown pdfkit Pillow

System Dependencies

# macOS
brew install wkhtmltopdf

# Linux
sudo apt-get install wkhtmltopdf

# 或下载二进制: https://wkhtmltopdf.org/downloads.html

Frequently Asked Questions

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 displayed incorrectly?

A: Make sure to wrap them with three backticks:

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

Q: Table formatting is messed up?

A: Use standard Markdown table syntax:

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

Q: wkhtmltopdf installation failed?

A:

# macOS
brew install wkhtmltopdf

# Linux
sudo apt-get install wkhtmltopdf

# 或下载二进制
# https://wkhtmltopdf.org/downloads.html

Q: Images are displayed incorrectly?

A: Use the complete workflow:

python scripts/workflow.py input.md

It will automatically handle all image issues.

Q: How do I upgrade from v1.0?

A: See the UPGRADE.md document for detailed upgrade steps.

Configuration Options

If you need to customize the 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'

File Structure

.claude/skills/markdown-to-pdf/
├── SKILL.md                      # 本文件
├── README.md                     # 快速开始
├── EXAMPLES.md                   # 使用示例
├── UPGRADE.md                    # 升级指南
├── WORKFLOW.md                   # 工作流文档
└── scripts/
    ├── convert.py                # 核心转换工具
    ├── analyze_images.py         # 图片分析
    ├── batch_convert_images.py   # 批量转换
    ├── update_markdown_refs.py   # 引用更新
    └── workflow.py               # 完整工作流

Technical Implementation

This Skill uses:

  • markdown: Official Markdown parsing library
  • pdfkit: HTML to PDF conversion (based on wkhtmltopdf)
  • Pillow: Image processing and format conversion
  • Apple Design System: SF fonts, professional color scheme, modern typography

Changelog

v2.0 (2025-01-30)

  • Replaced WeasyPrint with pdfkit
  • Removed the pango dependency
  • Added an image processing toolchain
  • Added a complete workflow
  • Improved image path handling
  • Improved error prompts

v1.0 (2025-12-24)

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