pandoc について
Pandoc を使う人向けの文書変換スキルです。形式変換、出力設定、よくある表示上の問題への対処方法を案内します。
主な機能
- 01Markdown から Word、PDF、HTML への変換
- 02Word 文書から Markdown への変換
- 03文書メタデータと目次の設定
- 04組版や Unicode に応じた PDF エンジンの選択
- 05リスト、表、コードのハイライト問題の対処
活用シーン
- 01Markdown のレポートを Word 文書にする
- 02Unicode テキストを含む Markdown から PDF を生成する
- 03リストと改行を保った HTML を作成する
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/pandocを入力して読み込まれたか確認します。
詳細
Pandoc ドキュメント変換スキル
万能ドキュメントコンバーターの pandoc を使って、ドキュメントをさまざまな形式に変換します。
前提条件
# Check if pandoc is installed
pandoc --version
# Install via Homebrew if needed
brew install pandoc
よく使う変換
Markdown から Word（.docx）への変換
# Basic conversion
pandoc input.md -o output.docx
# With table of contents
pandoc input.md --toc -o output.docx
# With custom reference doc (for styling)
pandoc input.md --reference-doc=template.docx -o output.docx
# Standalone with metadata
pandoc input.md -s --metadata title="Document Title" -o output.docx
Markdown から PDF への変換
# Requires LaTeX - install one of:
# brew install --cask basictex # Smaller (~100MB)
# brew install --cask mactex-no-gui # Full (~4GB)
# After install: eval "$(/usr/libexec/path_helper)" or new terminal
# Basic conversion (uses pdflatex)
pandoc input.md -o output.pdf
# With table of contents and custom margins
pandoc input.md -s --toc --toc-depth=2 -V geometry:margin=1in -o output.pdf
# Using xelatex (better Unicode support - box drawings, arrows, etc.)
export PATH="/Library/TeX/texbin:$PATH"
pandoc input.md --pdf-engine=xelatex -V geometry:margin=1in -o output.pdf
PDF エンジンの選択：
| エンジン | 使用する場面 |
|---|---|
pdflatex | デフォルト。ASCII 文字のみの場合 |
xelatex | Unicode 文字（矢印、罫線文字、絵文字）を使う場合 |
lualatex | 複雑な組版や OpenType フォントを使う場合 |
Markdown から HTML への変換
重要： 改行とリストを正しく処理するため、必ず -f gfm（GitHub Flavored Markdown）を使ってください。標準 Markdown では、連続した行がひとつの段落にまとめられます。
# RECOMMENDED: GitHub Flavored Markdown with full styling
pandoc -f gfm -s -H <(cat << 'STYLE'
<style>
body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;max-width:800px;margin:0 auto;padding:2em;line-height:1.6}
h1{border-bottom:2px solid #333;padding-bottom:0.3em}
h2{border-bottom:1px solid #ccc;padding-bottom:0.2em;margin-top:1.5em}
h3{margin-top:1.2em}
ul,ol{margin:0.5em 0 0.5em 1.5em;padding-left:1em}
ul{list-style-type:disc}ol{list-style-type:decimal}
li{margin:0.3em 0}ul ul,ol ul{list-style-type:circle;margin:0.2em 0 0.2em 1em}
table{border-collapse:collapse;width:100%;margin:1em 0}
th,td{border:1px solid #ddd;padding:8px;text-align:left}
th{background-color:#f5f5f5}
code{background-color:#f4f4f4;padding:2px 6px;border-radius:3px}
pre{background-color:#f4f4f4;padding:1em;overflow-x:auto;border-radius:5px}
blockquote{border-left:4px solid #ddd;margin:1em 0;padding-left:1em;color:#666}
</style>
STYLE
) input.md -o output.html
# Quick version (minimal styling)
pandoc -f gfm -s input.md -o output.html
# With hard line breaks (newlines become <br>)
pandoc -f markdown+hard_line_breaks -s input.md -o output.html
# Self-contained (embeds images/CSS)
pandoc -f gfm -s --embed-resources --standalone input.md -o output.html
形式オプション：
| オプション | 使用する場面 |
|---|---|
-f gfm | デフォルトの選択肢。リスト、改行、表を正しく処理します |
-f markdown+hard_line_breaks | すべての改行を <br> に変換します |
-f commonmark | CommonMark に厳密に準拠する場合 |
印刷して PDF 化するための HTML（LaTeX 不要）
LaTeX が使えない場合は、スタイルを適用した HTML を作成し、ブラウザーから印刷して PDF にします。
# Create inline CSS file
cat > /tmp/print-style.css << 'EOF'
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
max-width: 800px; margin: 0 auto; padding: 2em; line-height: 1.6; }
h1 { border-bottom: 2px solid #333; padding-bottom: 0.3em; }
h2 { border-bottom: 1px solid #ccc; padding-bottom: 0.2em; margin-top: 1.5em; }
h3 { margin-top: 1.2em; }
/* Lists - critical for proper rendering */
ul, ol { margin: 0.5em 0 0.5em 1.5em; padding-left: 1em; }
ul { list-style-type: disc; }
ol { list-style-type: decimal; }
li { margin: 0.3em 0; }
ul ul, ol ul { list-style-type: circle; margin: 0.2em 0 0.2em 1em; }
ul ol, ol ol { margin: 0.2em 0 0.2em 1em; }
ul ul ul, ol ul ul { list-style-type: square; }
/* Tables */
table { border-collapse: collapse; width: 100%; margin: 1em 0; }
th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
th { background-color: #f5f5f5; }
/* Code */
code { background-color: #f4f4f4; padding: 2px 6px; border-radius: 3px; }
pre { background-color: #f4f4f4; padding: 1em; overflow-x: auto; border-radius: 5px; }
/* Other */
blockquote { border-left: 4px solid #ddd; margin: 1em 0; padding-left: 1em; color: #666; }
@media print { body { max-width: none; } }
EOF
# Convert with embedded styles (ALWAYS use -f gfm)
pandoc -f gfm input.md -s --toc --toc-depth=2 -c /tmp/print-style.css --embed-resources --standalone -o output.html
# Open and print to PDF (Cmd+P > Save as PDF)
open output.html
Word から Markdown への変換
# Extract markdown from docx
pandoc input.docx -o output.md
# With ATX-style headers
pandoc input.docx --atx-headers -o output.md
便利なオプション
| オプション | 説明 |
|---|---|
-s / --standalone | ヘッダーとフッターを含む独立したドキュメントを生成します |
--toc | 目次を生成します |
--toc-depth=N | 目次の深さ（デフォルト：3） |
-V key=value | テンプレート変数を設定します |
--metadata key=value | メタデータ項目を設定します |
--reference-doc=FILE | スタイル設定に FILE を使用します（docx/odt） |
--template=FILE | カスタムテンプレートを使用します |
--highlight-style=STYLE | 構文ハイライトを設定します（pygments、tango など） |
--number-sections | セクションの見出しに番号を付けます |
-f FORMAT | 入力形式（自動検出されない場合） |
-t FORMAT | 出力形式（自動検出されない場合） |
形式識別子
| 形式 | 識別子 |
|---|---|
| Markdown | markdown、gfm（GitHub）、commonmark |
| Word | docx |
pdf | |
| HTML | html、html5 |
| LaTeX | latex |
| RST | rst |
| EPUB | epub |
| ODT | odt |
| RTF | rtf |
Google Docs のワークフロー
書式を保ったまま Markdown を Google Docs に取り込むには：
# 1. Convert to docx
pandoc document.md -o document.docx
# 2. Upload to Google Drive
# 3. Right-click > Open with > Google Docs
Google Docs は .docx ファイルを適切にインポートし、次の要素を保持します：
- 見出し
- 太字／斜体
- リスト（箇条書きと番号付き）
- 表
- リンク
- コードブロック（等幅フォント）
PSI ドキュメントの変換
表や複雑な書式を含む PSI ドキュメントの場合：
# Convert PSI markdown to Word
pandoc PSI-document.md \
--standalone \
--toc \
--toc-depth=2 \
-o PSI-document.docx
# Open for review
open PSI-document.docx
トラブルシューティング
リストや行がつながってしまう（HTML）
箇条書き、番号付きリスト、または連続する行がひとつの段落にまとまる場合：
原因： 標準 Markdown では、連続した行がひとつの段落として扱われます。リストの前には空行が必要です。
対処法： GitHub Flavored Markdown（-f gfm）を使います：
# Always use -f gfm for reliable formatting
pandoc -f gfm -s input.md -o output.html
# For documents where newlines should be <br> tags
pandoc -f markdown+hard_line_breaks -s input.md -o output.html
この問題が起きる理由：
- 標準 Markdown：
Line 1\nLine 2→<p>Line 1 Line 2</p>（結合される） - GFM：リストの検出が改善され、特殊なケースにも対応します
+hard_line_breaks：Line 1\nLine 2→Line 1<br>Line 2（改行が保持される）
表が正しく表示されない
Pandoc で表を表示するには、Markdown の表構文を正しく記述する必要があります：
| Header 1 | Header 2 |
|----------|----------|
| Cell 1 | Cell 2 |
コードブロックのハイライトが表示されない
言語識別子を付けたフェンス付きコードブロックを使います：
```python
def example():
pass
### PDF Generation Fails
**"pdflatex not found"** - Install LaTeX:
```bash
# Smaller option (~100MB)
brew install --cask basictex
# Full option (~4GB)
brew install --cask mactex-no-gui
# After install, update PATH
eval "$(/usr/libexec/path_helper)"
# Or open a new terminal
Unicode 文字（罫線文字、矢印、絵文字）のエラー：
# Use xelatex instead of pdflatex
export PATH="/Library/TeX/texbin:$PATH"
pandoc input.md --pdf-engine=xelatex -o output.pdf
LaTeX が使えない場合 — HTML から PDF に印刷するワークフローを使います：
pandoc input.md -s --toc -o output.html
open output.html
# Then Cmd+P > Save as PDF
セルフテスト
# Verify pandoc installation
pandoc --version | head -1
# Test basic conversion
echo "# Test\n\nHello **world**" | pandoc -f markdown -t html
コメント
Markdown 対応