SuperAPI AI Directory
Partner中文AI newsFavorites
Skillshuashu-md-to-pdf

huashu-md-to-pdf

Writing & research

View repository

Updated 10-15 16:47

About this skill

Markdown to PDF Skill

Convert Markdown documents into professional PDF whitepapers with an Apple design style.

Core Features

  1. Professional Typesetting: Book-level typesetting quality, with automatic handling of pagination, widows, and orphans
  2. Apple Design: SF font system, modern minimalist style, professional color scheme
  3. Complete Table of Contents: Automatically extracts the chapter structure, two-column layout, clickable navigation
  4. Perfect Markdown Support: Code blocks, tables, blockquotes, lists, and more are 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 the title and author

python scripts/convert.py input.md --title "Technical Whitepaper" --author "Hua Shu"


### 图片路径

Markdown 里的相对路径图片，是**相对 md 文件自身所在目录**解析的，目录名和文件名带中文都可以：

```markdown
![示意图](图片/架构图.png)     ← 和 md 文件同级的「图片」目录
![示意图](./assets/arch.png)

Missing images will print a warning during conversion and list the paths. Previously this situation was silently skipped, and the PDF was still generated, just without the images.

Known unresolved: in some environments, opening in macOS Preview shows garbled text

Some users have reported that generated PDFs appear garbled in macOS Preview, while opening them in a browser is normal.There is still no solution to this problem, and the cause has not yet been identified—it cannot be reproduced on a machine that uses Arial Unicode MS to render Chinese, and the reporter's font environment and weasyprint version are both unclear.

Do not try to use weasyprint's full_fonts=True to work around it. Tested: the Chinese fonts on macOS (PingFang.ttc, Songti.ttc, Hiragino Sans GB.ttc) are all TrueType Collections,full_fonts=True will stuff the entire collection's raw bytes into the PDF's /FontFile2(the magic is ttcf rather than a valid \x00\x01\x00\x00), and the result is thatthe file balloons to tens of MB, and it is still garbled—in testing, a passage of Chinese went from 10 KB to 43 MB, and rendered as "Oě 据⊤". It makes the problem worse, not an escape hatch.

When you encounter garbled text, you can first try: upgrading weasyprint, or switching to a non-collection font in the CSS.

Markdown Document Requirements

Your Markdown document should follow this structure:

# 文档标题

## 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 in 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 to jump to the corresponding chapter

Body Typesetting

  • 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
  • Automatic page-break avoidance

Tables

  • Clear grid lines
  • Light gray header
  • Automatically repeat headers (when long tables span pages)

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 section format:

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

Q: Code blocks display 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: How do I change the font?

A: Edit the CSS in scripts/convert.py , and 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 the first time you use it:

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 White Paper

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

Script Description

  • scripts/convert.py - Main conversion script
  • scripts/styles.css - CSS style definitions (already embedded in the script)
  • templates/cover.html - Cover template (already 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 scheme, modern typography

Changelog

v1.0 (2025-12-24)

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

Produced by Huashu | AI Native Coder · Independent Developer WeChat Official Account "Huashu" | 300k+ followers | AI tools and productivity improvement Representative works: Xiaomao Fill Light (Top 1 on App Store Paid Chart) · 《一本书玩转DeepSeek》