huashu-md-to-pdf

Markdown to PDF スキル

Markdown ドキュメントを、Apple デザインスタイルのプロフェッショナルな PDF ホワイトペーパーに変換します。

主な機能

1. プロフェッショナルな組版：書籍品質の組版を実現し、改ページや孤立行を自動で処理します
2. Apple デザイン：SF フォントシステム、モダンでシンプルなスタイル、プロフェッショナルな配色
3. 完全な目次：章構成を自動で抽出し、2 列レイアウトで表示します。クリックして移動できます
4. Markdown を完全サポート：コードブロック、表、引用、リストなどをすべて正しくレンダリングします

使用方法

基本的な使い方

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

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

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

画像パス

Markdown 内の相対パス画像は、md ファイル自体があるディレクトリを基準に解決されます。ディレクトリ名やファイル名に日本語が含まれていても問題ありません。

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

見つからない画像がある場合は、変換時に警告とパスが表示されます。以前はこのような場合、何も表示されずにスキップされ、PDF はそのまま生成されていましたが、画像は含まれていませんでした。

既知の未解決問題：一部の環境で macOS の「プレビュー」で開くと文字化けする

生成された PDF が macOS の「プレビュー」では文字化けするものの、ブラウザーでは正常に開けるという報告があります。この問題にはまだ解決策がありません。原因も特定できていません。Arial Unicode MS で中国語をレンダリングするマシンでは再現できず、報告者のフォント環境と weasyprint のバージョンも不明です。

weasyprint の full_fonts=True で回避しようとしないでください。 実測では、macOS の中国語フォント（Pingfang.ttc、Songti.ttc、Hiragino Sans GB.ttc）はいずれも TrueType Collection です。full_fonts=True を指定すると、collection 全体の生バイト列が PDF の /FontFile2 に格納されます（magic は ttcf で、正しい \x00\x01\x00\x00 ではありません）。その結果、ファイルサイズが数十 MB に膨れ上がるうえ、文字化けもそのままです。実測では、中国語のテキストが 10 KB から 43 MB に増え、レンダリング結果は「Oě 据⊤」になりました。問題を悪化させるだけで、解決策にはなりません。

文字化けが発生した場合は、weasyprint をアップグレードするか、CSS で collection ではないフォントに変更してみてください。

Markdown ドキュメントの要件

Markdown ドキュメントは、次の構成に従ってください。

# 文档标题

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

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

重要なルール：

• メインセクション：## 1. タイトル（数字 + ピリオド + スペース + タイトル）
• サブセクション：### 1.1 タイトル（数字.数字 + スペース + タイトル）
• この形式にすると、目次を正しく抽出できます

デザインの特徴

表紙デザイン

• 淡いグレーのグラデーション背景
• 大見出し：64pt、シンプルでモダン
• サブタイトルとメタ情報

目次デザイン

• 2 列レイアウトで 1 ページに表示
• メインセクションは太字、サブセクションはインデント
• 対応するセクションにクリックして移動できます

本文の組版

• SF フォントファミリー（Apple のデザイン言語）
• 行の高さは 1.7 で、快適に読めます
• セクションごとに自動で改ページ
• 孤立行を制御

コードブロック

• 薄いグレーの背景 + 細い枠線
• 角丸 8px
• SF Mono 等幅フォント
• ページをまたがないように自動調整

表

• 見やすいグリッド線
• 薄いグレーのヘッダー
• 長い表が改ページする場合も、ヘッダーを自動で保持

設定オプション

スタイルをカスタマイズする場合は、scripts/convert.py の CSS 変数を変更してください。

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

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

よくある質問

Q: 目次が空なのはなぜですか？

A: Markdown のセクション形式が正しいことを確認してください。

• ## タイトル ではなく、## 1. タイトル を使用してください
• ### タイトル ではなく、### 1.1 タイトル を使用してください

Q: コードブロックが正しく表示されないのはなぜですか？

A: 3 つのバッククォートで囲んでいることを確認してください。

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

Q: 表の書式が崩れるのはなぜですか？

A: 標準的な Markdown の表構文を使用してください。

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

Q: フォントを変更するにはどうすればよいですか？

A: scripts/convert.py の CSS を編集し、font-family 属性を変更してください。

Q: 生成された PDF のサイズが大きすぎる場合はどうすればよいですか？

A: 画像が大量に含まれていないか確認し、画像を圧縮するか、外部リンクの使用を検討してください。

依存関係のインストール

初回使用時に、Python の依存関係をインストールしてください。

pip3 install markdown2 weasyprint

WeasyPrint のインストールで問題が発生した場合（macOS）：

brew install pango
pip3 install weasyprint

例

技術ドキュメントを生成する

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

ホワイトペーパーを生成する

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

スクリプトの説明

• scripts/convert.py - メインの変換スクリプト
• scripts/styles.css - CSS スタイル定義（スクリプトに埋め込み済み）
• templates/cover.html - 表紙テンプレート（スクリプトに埋め込み済み）

技術的な実装

この Skill では、次の技術を使用しています。

• markdown2：Markdown の解析（拡張構文をサポート）
• WeasyPrint：HTML から PDF への変換（CSS3 をサポート）
• Apple デザインシステム：SF フォント、プロフェッショナルな配色、モダンな組版

更新履歴

v1.0 (2025-12-24)

• 初期バージョン
• Markdown の全構文をサポート
• Apple デザインスタイル
• 目次を自動生成
• 書籍品質の組版

---

花叔制作 | AI Native Coder · 独立開発者 公式アカウント「花叔」| フォロワー 30 万人以上 | AI ツールと生産性向上 代表作：小猫补光灯（AppStore有料ランキング Top1）·『一本书玩转DeepSeek』