关于 pandoc
面向 Pandoc 使用者的文档转换技能，提供格式转换、输出控制和常见渲染问题的处理方法，适用于日常文档制作与整理。
主要功能
- 01将 Markdown 转换为 Word、PDF 和 HTML
- 02将 Word 文档转换为 Markdown
- 03设置文档元数据和目录
- 04按排版与 Unicode 需求选择 PDF 引擎
- 05排查列表、表格和代码高亮问题
适用场景
- 01将 Markdown 报告制作为 Word 文档
- 02生成包含 Unicode 文本的 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→<p>Line 1<br>Line 2</p>（保留换行）
表格无法渲染
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