Markdown 转 Office 技能

概述

本技能支持使用 Pandoc（通用文档转换器）将 Markdown 转换为多种 Office 格式。将您的 Markdown 文件转换为专业的 Word 文档、PowerPoint 演示文稿、PDF 等，同时保留格式和结构。

使用方法

1. 提供 Markdown 内容或文件
2. 指定目标格式（docx、pptx、pdf 等）
3. 可选：提供参考模板用于样式设置
4. 我将使用 Pandoc 以最佳设置进行转换

示例提示：

• "将这个 README.md 转换为专业的 Word 文档"
• "将我的 Markdown 笔记转换为 PowerPoint 演示文稿"
• "从 Markdown 生成带有自定义样式的 PDF"
• "使用公司模板从 Markdown 创建 Word 文档"

领域知识

Pandoc 基础

# 基本转换
pandoc input.md -o output.docx
pandoc input.md -o output.pdf
pandoc input.md -o output.pptx

# 使用模板
pandoc input.md --reference-doc=template.docx -o output.docx

# 多个输入
pandoc ch1.md ch2.md ch3.md -o book.docx

支持的转换

源格式	目标格式	命令
Markdown	Word	pandoc in.md -o out.docx
Markdown	PDF	pandoc in.md -o out.pdf
Markdown	PowerPoint	pandoc in.md -o out.pptx
Markdown	HTML	pandoc in.md -o out.html
Markdown	LaTeX	pandoc in.md -o out.tex
Markdown	EPUB	pandoc in.md -o out.epub

Markdown 转 Word (.docx)

基本转换

pandoc document.md -o document.docx

使用模板（参考文档）

# 首先通过转换示例创建模板
pandoc sample.md -o reference.docx

# 在 Word 中编辑 reference.docx 样式，然后使用它
pandoc input.md --reference-doc=reference.docx -o output.docx

带目录

pandoc document.md --toc --toc-depth=3 -o document.docx

带元数据

pandoc document.md \
  --metadata title="我的报告" \
  --metadata author="张三" \
  --metadata date="2024-01-15" \
  -o document.docx

Markdown 转 PDF

通过 LaTeX（最佳质量）

# 需要安装 LaTeX
pandoc document.md -o document.pdf

# 自定义设置
pandoc document.md \
  --pdf-engine=xelatex \
  -V geometry:margin=1in \
  -V fontsize=12pt \
  -o document.pdf

通过 HTML/wkhtmltopdf

pandoc document.md \
  --pdf-engine=wkhtmltopdf \
  --css=style.css \
  -o document.pdf

PDF 选项

pandoc document.md \
  -V papersize:a4 \
  -V geometry:margin=2cm \
  -V fontfamily:libertinus \
  -V colorlinks:true \
  --toc \
  -o document.pdf

Markdown 转 PowerPoint (.pptx)

基本转换

pandoc slides.md -o presentation.pptx

幻灯片的 Markdown 结构

---
title: 演示文稿标题
author: 作者姓名
date: 2024年1月
---

# 章节标题（创建章节分隔符）

## 幻灯片标题

- 要点 1
- 要点 2
  - 子要点

## 另一张幻灯片

内容在此

::: notes
演讲者备注在此（幻灯片中不可见）
:::

## 带图片的幻灯片

![描述](image.png){width=80%}

## 两列幻灯片

:::::::::::::: {.columns}
::: {.column width="50%"}
左列内容
:::

::: {.column width="50%"}
右列内容
:::
::::::::::::::

使用模板

# 使用公司 PowerPoint 模板
pandoc slides.md --reference-doc=template.pptx -o presentation.pptx

YAML 前置元数据

在 Markdown 顶部添加元数据：

---
title: "文档标题"
author: "作者姓名"
date: "2024-01-15"
abstract: "简要描述"
toc: true
toc-depth: 2
numbersections: true
geometry: margin=1in
fontsize: 11pt
documentclass: report
---

# 第一章
...

Python 集成

import subprocess
import os

def md_to_docx(input_path, output_path, template=None):
    """将 Markdown 转换为 Word 文档。"""
    cmd = ['pandoc', input_path, '-o', output_path]
    
    if template:
        cmd.extend(['--reference-doc', template])
    
    subprocess.run(cmd, check=True)
    return output_path

def md_to_pdf(input_path, output_path, **options):
    """将 Markdown 转换为 PDF，带选项。"""
    cmd = ['pandoc', input_path, '-o', output_path]
    
    if options.get('toc'):
        cmd.append('--toc')
    
    if options.get('margin'):
        cmd.extend(['-V', f"geometry:margin={options['margin']}"])
    
    subprocess.run(cmd, check=True)
    return output_path

def md_to_pptx(input_path, output_path, template=None):
    """将 Markdown 转换为 PowerPoint。"""
    cmd = ['pandoc', input_path, '-o', output_path]
    
    if template:
        cmd.extend(['--reference-doc', template])
    
    subprocess.run(cmd, check=True)
    return output_path

pypandoc（Python 封装）

import pypandoc

# 简单转换
output = pypandoc.convert_file('input.md', 'docx', outputfile='output.docx')

# 带选项
output = pypandoc.convert_file(
    'input.md', 
    'docx',
    outputfile='output.docx',
    extra_args=['--toc', '--reference-doc=template.docx']
)

# 从字符串转换
md_content = "# Hello\n\nThis is markdown."
output = pypandoc.convert_text(md_content, 'docx', format='md', outputfile='output.docx')

最佳实践

1. 使用模板：创建参考文档以保持品牌一致性
2. 结构化标题：使用一致的标题级别（## 用于幻灯片，# 用于章节）
3. 逐步测试：先转换小部分以验证格式
4. 包含元数据：使用 YAML 前置元数据设置文档属性
5. 处理图片：使用相对路径并指定尺寸

常见模式

批量转换

import subprocess
from pathlib import Path

def batch_convert(input_dir, output_format, output_dir=None):
    """转换目录中的所有 Markdown 文件。"""
    input_path = Path(input_dir)
    output_path = Path(output_dir) if output_dir else input_path
    
    for md_file in input_path.glob('*.md'):
        output_file = output_path / md_file.with_suffix(f'.{output_format}').name
        subprocess.run([
            'pandoc', str(md_file), '-o', str(output_file)
        ], check=True)
        print(f"已转换: {md_file.name} -> {output_file.name}")

batch_convert('./docs', 'docx', './output')

报告生成器

def generate_report(title, sections, output_path, template=None):
    """从结构化数据生成 Word 报告。"""
    
    # 构建 Markdown
    md_content = f"""---
title: "{title}"
date: "{datetime.now().strftime('%Y年%m月%d日')}"
---

"""
    for section_title, content in sections.items():
        md_content += f"# {section_title}\n\n{content}\n\n"
    
    # 写入临时文件
    with open('temp_report.md', 'w') as f:
        f.write(md_content)
    
    # 转换
    cmd = ['pandoc', 'temp_report.md', '-o', output_path, '--toc']
    if template:
        cmd.extend(['--reference-doc', template])
    
    subprocess.run(cmd, check=True)
    os.remove('temp_report.md')

示例

示例 1：技术文档

import subprocess

# 创建全面的 Markdown
doc = """---
title: "API 文档"
author: "开发团队"
date: "2024-01-15"
toc: true
toc-depth: 2
---

# 简介

本文档描述了我们服务的 REST API。

## 身份验证

所有 API 请求需要在请求头中包含 API 密钥：

Authorization: Bearer YOUR_API_KEY

## 端点

### GET /users

获取所有用户。

**响应：**

| 字段 | 类型 | 描述 |
|------|------|------|
| id | integer | 用户 ID |
| name | string | 全名 |
| email | string | 电子邮件地址 |

### POST /users

创建新用户。

**请求体：**

```json
{
  "name": "John Doe",
  "email": "john@example.com"
}

错误码

码	含义
400	错误请求
401	未授权
404	未找到
500	服务器错误
"""

保存 Markdown

with open('api_docs.md', 'w') as f:
f.write(doc)

转换为 Word

subprocess.run([
'pandoc', 'api_docs.md',
'-o', 'api_documentation.docx',
'--toc',
'--reference-doc', 'company_template.docx'
], check=True)

转换为 PDF

subprocess.run([
'pandoc', 'api_docs.md',
'-o', 'api_documentation.pdf',
'--toc',
'-V', 'geometry:margin=1in',
'-V', 'fontsize=11pt'
], check=True)

#### 示例 2：从 Markdown 生成演示文稿
```python
slides_md = """---
title: "第四季度业务回顾"
author: "销售团队"
date: "2024年1月"
---

# 概述

## 议程

- 第四季度业绩总结
- 区域亮点
- 2024年展望
- 问答环节

# 第四季度业绩

## 关键指标

- 收入：1250万美元（同比增长15%）
- 新客户：250
- 留存率：94%

## 区域业绩

:::::::::::::: {.columns}
::: {.column width="50%"}
**北美**

- 收入：620万美元
- 增长：+18%
:::

::: {.column width="50%"}
**欧洲**

- 收入：410万美元
- 增长：+12%
:::
::::::::::::::

# 2024年展望

## 战略重点

1. 拓展亚太地区业务
2. 推出新产品线
3. 改善客户入职体验

## 收入目标

| 季度 | 目标 |
|------|------|
| Q1 | 1300万美元 |
| Q2 | 1400万美元 |
| Q3 | 1500万美元 |
| Q4 | 1600万美元 |

# 谢谢

## 有问题吗？

联系方式：sales@company.com
"""

with open('presentation.md', 'w') as f:
    f.write(slides_md)

subprocess.run([
    'pandoc', 'presentation.md',
    '-o', 'q4_review.pptx',
    '--reference-doc', 'company_slides.pptx'
], check=True)

局限性

• 复杂的 Word 格式可能无法完美转换
• PDF 转换需要 LaTeX 或 wkhtmltopdf
• 不支持 PowerPoint 动画
• 某些高级表格可能需要手动调整
• 图片定位可能较复杂

安装

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
choco install pandoc

# Python 封装
pip install pypandoc

资源

• Pandoc 用户指南
• GitHub 仓库
• Pandoc 模板
• pypandoc 文档