📚 专为AI生成程序设计的智能文档生成器
Code2Doce 是一个功能强大的文档自动化生成工具，专为处理复杂的技术文档和代码文档化需求而设计。它能够将Markdown源文件、Mermaid图表和SCL控制代码转换为专业的PDF文档，特别适合工业自动化、PLC编程和AI生成程序的文档化需求。
核心特点：
- 🚀 智能渲染引擎：自动处理Mermaid图表，无需手动转换
- 🌐 网络图片缓存：自动下载并转换网络图片，支持离线构建
- 🔤 中文优化：专为中文技术文档设计的排版系统
- ⚙️ SCL代码支持：完美支持西门子SCL/ST语言的代码高亮和排版
- 📊 表格智能处理：复杂表格自动换行和列宽优化
- 🤖 MCP集成：通过Model Context Protocol与AI助手无缝协作
- 🔌 VSCode扩展：一键安装、可视化配置的扩展支持
Code2Doce 提供完整的 Model Context Protocol (MCP) 服务器实现,让您可以通过 GitHub Copilot 等 AI 助手直接使用文档生成工具:
功能亮点:
- ✅ 5个专业工具: 渲染图表、生成PDF、分析SCL代码、浏览库文件、创建文档
- ✅ 零配置启动: 自动检测项目环境和Python路径
- ✅ 流式响应: 实时反馈工具执行进度
- ✅ 智能缓存: 避免重复渲染提升性能
使用示例 (在 Copilot Chat 中):
@code2doce 用 2.0 倍缩放渲染 README.md 中的 Mermaid 图表
@code2doce 分析 library/LAF/LAF_ControlSclSequence.scl 的结构
@code2doce 为 library/LUC/LUC_InterfaceManager.scl 创建文档模板
👉 查看 MCP_README.md 了解详细配置
一键安装,开箱即用!
扩展提供了类似 VSCode Marketplace 扩展的用户体验:
-
📦 一键安装依赖
- 命令面板 →
Code2Doce: Install MCP Dependencies - 自动安装 mcp, playwright, requests, Pillow
- 自动下载 Chromium 浏览器
- 命令面板 →
-
⚙️ 可视化配置
- 设置界面直接勾选启用/禁用
- 自定义 Python 路径
- 自动安装提示开关
-
📊 侧边栏视图
- 实时查看 MCP Server 状态
- 依赖安装状态指示
- 可用工具列表展示
# 1. 构建并安装扩展
cd vscode-extension
.\build-and-install.ps1
# 2. 重启 VSCode
# 3. 打开命令面板 (Ctrl+Shift+P)
Code2Doce: Install MCP Dependencies
# 4. 启用 MCP 服务器
Code2Doce: Enable MCP Server
# 5. 在 Copilot Chat 中使用
@code2doce 你有哪些工具?👉 查看 vscode-extension/QUICKSTART.md 了解详细使用
- 智能检测：扫描Markdown中的所有Mermaid代码块
- 批量渲染：自动转换为高清PNG图片（支持自定义缩放）
- 自动链接：在文档中自动插入图片引用
- 哈希命名：基于内容生成唯一文件名，避免冲突
- 自动下载：检测并下载文档中的网络图片
- 格式转换：统一转换为PNG格式，确保兼容性
- 智能缓存：已下载的图片不重复下载
- 相对路径：自动更新为本地相对路径
- 字体配置：默认使用SimSun宋体，可自定义
- 页面布局：A4纸张，优化的边距（左20mm，右12mm）
- XeLaTeX引擎：完美支持中文字符和标点
- 表格处理：智能换行和列宽自适应
- 语法高亮：支持西门子PLC的SCL/ST语言
- 结构化显示：TYPE、STRUCT、FUNCTION_BLOCK等结构清晰展示
- 注释保留：完整保留代码注释和格式
Code2Doce/
├── 📂 Builder/ # 构建工具和资源
│ ├── 🔧 render-mermaid.cmd # Windows批处理包装器
│ ├── � render-mermaid.py # Python渲染脚本（Mermaid + 网络图片）
│ ├── 🎨 pandoc-header-includes.tex # LaTeX头部配置文件
│ ├── 📊 pandoc-wrap-tables.lua # 表格处理Lua过滤器
│ └── 🖼️ img/ # 生成的图片存储目录
│ ├── mermaid-*.png # 渲染的Mermaid图表
│ └── downloaded-*.png # 下载的网络图片
├── 📂 SCL/ # SCL示例代码
│ ├── ⚙️ LAF_ControlSclSequence.scl # 序列控制类型定义
│ ├── 📊 LAF_StatusSclSequence.scl # 状态序列类型定义
│ ├── 🔌 LBC_MotorStarterCn.scl # 电机启动器连接
│ ├── 🎛️ LBC_TwoWayActuatorCn.scl # 双向执行器连接
│ └── 🔗 LUC_InterfaceManager.scl # 接口管理器
├── 📖 README.md # 项目说明文档
└── 📄 LICENSE # MIT开源许可证
| 软件 | 版本要求 | 用途 | 安装方法 |
|---|---|---|---|
| Pandoc | 2.0+ | 文档转换核心引擎 | winget install JohnMacFarlane.Pandoc 或 官网下载 |
| MiKTeX | 最新版 | 提供XeLaTeX引擎 | winget install MiKTeX.MiKTeX 或 官网下载 |
| Python | 3.6+ | 运行渲染脚本 | winget install Python.Python.3.12 或 官网下载 |
🎉 重要更新: 现在使用 纯 Python 实现渲染 Mermaid,无需安装 Node.js 和 mermaid-cli!
运行渲染脚本需要以下Python包：
# 方法1: 使用 requirements.txt (推荐)
pip install -r Builder/requirements.txt
# 方法2: 手动安装
pip install playwright requests Pillow
# 安装完成后，下载 Chromium 浏览器 (仅需一次)
playwright install chromium依赖说明：
playwright：用于在无头浏览器中渲染 Mermaid 图表requests：用于下载网络图片Pillow：用于图片格式转换和处理
在VSCode的 settings.json 中添加以下配置：
{
"pandoc.pdfOptString": "--from gfm --pdf-engine xelatex -V CJKmainfont=SimSun --lua-filter=.\\Builder\\pandoc-wrap-tables.lua --include-in-header=.\\Builder\\pandoc-header-includes.tex --verbose"
}配置说明：
--from gfm：使用GitHub Flavored Markdown格式--pdf-engine xelatex：使用XeLaTeX引擎（支持中文）-V CJKmainfont=SimSun：设置中文字体为宋体--lua-filter：应用表格处理过滤器--include-in-header：包含LaTeX头部配置--verbose：显示详细输出信息
Windows系统：默认已安装SimSun字体，无需额外配置
其他系统：可修改 pandoc-header-includes.tex 中的字体设置：
% 将SimSun替换为系统中的其他中文字体
\setCJKmainfont{Microsoft YaHei} % 或 NotoSansCJK, STSong等确保已安装所有必需软件（参见上方"环境要求与配置"章节）。
# 进入项目目录
cd <项目根目录>
# 安装Python依赖
pip install -r Builder/requirements.txt
# 安装 Chromium 浏览器 (仅需一次)
playwright install chromium🖼️ 关于图片路径的重要说明：
Code2Doce 已优化图片路径处理，支持多级目录的图片引用：
- ✅ 当前目录图片：
 - ✅ Builder目录图片：
 - ✅ Builder/img目录图片：
← Mermaid渲染的图片默认保存位置
PDF生成时会自动在以下路径查找图片：
- 当前工作目录 (
.) - Builder目录 (
./Builder) - Builder/img目录 (
./Builder/img)
💡 最佳实践：Mermaid图表渲染后会自动保存到
Builder/img/目录，并在Markdown中插入正确的引用路径。您无需手动调整路径，生成PDF时会自动包含所有图片。
# 使用Python运行渲染脚本
python .\Builder\render-mermaid.py --root-dir "." --img-dir ".\Builder\img" --scale 2参数说明：
--root-dir：要扫描的根目录（默认：当前目录）--img-dir：图片保存目录（默认：./Builder/img）--scale：Mermaid图表缩放倍数（默认：2.0，推荐值：1.5-3.0）
脚本功能：
- 扫描所有Markdown文件中的Mermaid代码块
- 在无头浏览器中渲染每个Mermaid图表为PNG图片
- 自动在代码块后插入图片引用
- 检测并下载文档中的网络图片
- 将网络图片转换为PNG并更新链接
方式A：使用VSCode Pandoc插件（推荐）
- 在VSCode中打开Markdown文件（如
README.md） - 按下
Ctrl+K然后按P（或使用命令面板搜索"Pandoc Render"） - 选择 "pdf" 格式
- 等待生成完成，PDF将保存在同一目录
方式B：使用命令行
# 基础命令
pandoc README.md -o README.pdf `
--from gfm `
--pdf-engine xelatex `
-V CJKmainfont=SimSun `
--lua-filter=.\Builder\pandoc-wrap-tables.lua `
--include-in-header=.\Builder\pandoc-header-includes.tex
# 添加详细输出（用于调试）
pandoc README.md -o README.pdf `
--from gfm `
--pdf-engine xelatex `
-V CJKmainfont=SimSun `
--lua-filter=.\Builder\pandoc-wrap-tables.lua `
--include-in-header=.\Builder\pandoc-header-includes.tex `
--verbose# 1. 编写文档
code README.md # 在VSCode中编写或编辑Markdown
# 2. 渲染图表和下载图片
python .\Builder\render-mermaid.py
# 3. 生成PDF（VSCode插件或命令行）
# 使用VSCode插件：Ctrl+K P 选择pdf
# 或命令行：
pandoc README.md -o README.pdf --from gfm --pdf-engine xelatex -V CJKmainfont=SimSun --lua-filter=.\Builder\pandoc-wrap-tables.lua --include-in-header=.\Builder\pandoc-header-includes.tex
# 4. 查看生成的PDF
start README.pdf症状：
- PDF生成成功，但图片位置显示为空白或"Image not found"
- LaTeX警告：
File './Builder/img/xxx.png' not found
原因分析：
- 最常见：未运行Mermaid渲染脚本，图片文件不存在
- 图片路径不在Pandoc的资源查找路径中
- 图片文件损坏或格式不支持
解决方案：
# 步骤1：确认运行了渲染脚本
python .\Builder\render-mermaid.py
# 步骤2：检查图片是否已生成
dir .\Builder\img\*.png
# 步骤3：验证Markdown中的图片引用
# 正确格式示例：
# 
# 步骤4：如果使用MCP或VSCode扩展，确保使用v1.1.2+版本
# 早期版本可能不支持Builder/img路径支持的图片路径格式（v1.1.2+）：
- ✅
- 当前目录 - ✅
- Builder目录 - ✅
- Builder/img目录（Mermaid默认位置） - ✅
- 相对路径 - ❌
- 不推荐使用绝对路径
💡 提示：Code2Doce v1.1.2+ 已自动配置多个资源路径（
.、./Builder、./Builder/img），您无需手动调整Markdown中的图片引用路径。
错误信息：
! LaTeX Error: Cannot determine size of graphic in ./mermaid-xxx.svg
或
! Package pdftex.def Error: File `./mermaid-xxx.svg' not found
原因：未运行Mermaid渲染脚本，或SVG文件未转换为PNG
解决方案：
# 运行渲染脚本
python .\Builder\render-mermaid.py
# 确认图片已生成
dir .\Builder\img\*.png
# 检查Markdown文件中是否已插入PNG链接原因：系统缺少指定的中文字体或字体配置错误
解决方案：
方案A：安装SimSun字体（Windows通常已安装）
方案B：更改为其他可用字体
# 查看系统可用中文字体
fc-list :lang=zh
# 修改pandoc-header-includes.tex中的字体设置
# \setCJKmainfont{Microsoft YaHei} # 微软雅黑
# \setCJKmainfont{STSong} # 华文宋体错误信息：
Error downloading image from https://...
原因：网络连接问题、图片链接失效或需要代理
解决方案：
# 检查网络连接
Test-NetConnection -ComputerName www.github.com -Port 443
# 如需代理，设置环境变量
$env:HTTP_PROXY="http://proxy.example.com:8080"
$env:HTTPS_PROXY="http://proxy.example.com:8080"
# 重新运行脚本
python .\Builder\render-mermaid.py错误信息：
Failed to initialize browser: Executable doesn't exist
或
ModuleNotFoundError: No module named 'playwright'
原因：未安装 Playwright 或未下载 Chromium 浏览器
解决方案：
# 安装 Playwright
pip install playwright
# 下载 Chromium 浏览器
playwright install chromium
# 验证安装
python -c "from playwright.sync_api import sync_playwright; print('Playwright OK')"原因：表格列过多或内容过长
解决方案：
方案A：使用Lua过滤器自动换行（已配置）
方案B：手动调整表格
<!-- 使用较短的列标题 -->
| 短列1 | 短列2 | 短列3 |
|------|------|------|
<!-- 或拆分为多个小表格 -->原因：首次运行时MiKTeX需要下载宏包
解决方案：
# 设置MiKTeX自动安装宏包
initexmf --set-config-value [MPM]AutoInstall=1
# 或手动安装常用宏包
mpm --install=xecjk
mpm --install=ctex
mpm --install=fontspec错误信息：
FileNotFoundError: [WinError 3] 系统找不到指定的路径
原因：不在项目根目录运行命令，或路径使用了错误的分隔符
解决方案：
# 确保在项目根目录
cd <项目根目录>
# Windows PowerShell中使用反斜杠或点斜杠
python .\Builder\render-mermaid.py
# 或使用正斜杠（也支持）
python ./Builder/render-mermaid.py错误信息：
ModuleNotFoundError: No module named 'requests'
解决方案：
# 检查已安装的包
python -m pip list
# 安装缺失的包
python -m pip install requests Pillow
# 如果pip版本过旧，先升级pip
python -m pip install --upgrade pipMermaid图表的渲染倍率直接影响生成PNG图片的质量和文件大小。您可以根据实际需求灵活调整。
| 倍率 | 质量 | 文件大小 | 适用场景 | 推荐度 |
|---|---|---|---|---|
| 1.0x | 标准 | 最小 | 网页预览、快速草稿 | ⭐⭐⭐ |
| 2.0x | 清晰 | 适中 | 日常文档、PDF输出 | ⭐⭐⭐⭐⭐ |
| 3.0x | 高清 | 较大 | 专业文档、演示文稿 | ⭐⭐⭐⭐ |
| 4.0x | 超高清 | 大 | 印刷出版、超大屏幕 | ⭐⭐⭐ |
💡 推荐设置：默认的
2.0x倍率在质量和文件大小之间取得了良好平衡，适合大多数场景。
方式 1：命令行参数（推荐）
最直观的方式，直接在命令行指定倍率：
# 使用默认倍率（2.0x）
python .\Builder\render-mermaid.py
# 使用高清倍率（3.0x）- 适合专业文档
python .\Builder\render-mermaid.py --scale 3.0
# 使用超高清倍率（4.0x）- 适合印刷
python .\Builder\render-mermaid.py --scale 4.0
# 使用标准倍率（1.0x）- 适合快速预览
python .\Builder\render-mermaid.py --scale 1.0
# 使用自定义倍率（2.5x）- 精细调节
python .\Builder\render-mermaid.py --scale 2.5方式 2：环境变量
适合批处理或CI/CD环境，无需修改命令：
# Windows PowerShell
$env:MERMAID_PNG_SCALE="3.0"
python .\Builder\render-mermaid.py
# 临时设置（仅当前会话有效）
$env:MERMAID_PNG_SCALE="4.0"; python .\Builder\render-mermaid.py
# 永久设置（需要管理员权限）
[System.Environment]::SetEnvironmentVariable('MERMAID_PNG_SCALE', '3.0', 'User')# Linux/Mac
export MERMAID_PNG_SCALE=3.0
python ./Builder/render-mermaid.py
# 或单行命令
MERMAID_PNG_SCALE=3.0 python ./Builder/render-mermaid.py方式 3：修改默认值（不推荐）
如果您总是使用特定倍率，可以修改脚本中的默认值：
编辑 Builder/render-mermaid.py，找到以下行并修改默认值：
parser.add_argument('--scale', type=float, default=2.0, # 修改这里的 2.0
help='Scale factor for Mermaid diagrams')根据输出格式选择：
# PDF文档（推荐 2.0-3.0x）
python .\Builder\render-mermaid.py --scale 2.5
# 网页/HTML（推荐 1.5-2.0x）
python .\Builder\render-mermaid.py --scale 1.5
# 印刷品/海报（推荐 3.0-4.0x）
python .\Builder\render-mermaid.py --scale 4.0
# 快速预览/草稿（推荐 1.0x）
python .\Builder\render-mermaid.py --scale 1.0根据图表复杂度选择：
# 简单流程图（2.0x足够）
python .\Builder\render-mermaid.py --scale 2.0
# 复杂时序图或类图（建议 3.0x）
python .\Builder\render-mermaid.py --scale 3.0
# 包含大量文字的图表（建议 3.0-4.0x）
python .\Builder\render-mermaid.py --scale 3.5倍率越高，渲染时间和文件大小都会增加：
| 倍率 | 相对渲染时间 | 相对文件大小 | 内存占用 |
|---|---|---|---|
| 1.0x | 1x (基准) | 1x (基准) | 低 |
| 2.0x | ~1.2x | ~4x | 中 |
| 3.0x | ~1.5x | ~9x | 中高 |
| 4.0x | ~2x | ~16x | 高 |
⚠️ 注意：倍率翻倍时，文件大小会增加约4倍（因为图片是二维的）。
如果需要更改已有图表的倍率，需要删除旧图片后重新渲染：
# 1. 备份现有图片（可选）
Copy-Item .\Builder\img .\Builder\img_backup -Recurse
# 2. 删除旧的Mermaid图片
Remove-Item .\Builder\img\mermaid-*.png
# 3. 使用新倍率重新渲染
python .\Builder\render-mermaid.py --scale 3.0
# 4. 如果满意，删除备份
Remove-Item .\Builder\img_backup -Recurse查看完整的参数说明和使用示例：
python .\Builder\render-mermaid.py --help将图片保存到其他位置：
python .\Builder\render-mermaid.py --img-dir ".\docs\images"# 只处理SCL目录下的Markdown文件
python .\Builder\render-mermaid.py --root-dir ".\SCL"编辑 Builder/pandoc-header-includes.tex 以自定义：
- 页边距：修改
\geometry{...}部分 - 字体：修改
\setCJKmainfont{...}部分 - 行距：添加
\linespread{1.5}等
示例：
% 自定义页边距为均匀的25mm
\geometry{a4paper, margin=25mm}
% 使用微软雅黑字体
\setCJKmainfont{Microsoft YaHei}
% 设置1.5倍行距
\linespread{1.5}创建批处理脚本 build-all.ps1：
# build-all.ps1
$docs = @("README.md", "SCL\Documentation.md", "Builder\Guide.md")
# 渲染所有图表
python .\Builder\render-mermaid.py
# 生成所有PDF
foreach ($doc in $docs) {
Write-Host "Generating PDF for $doc..."
$output = $doc -replace '\.md$', '.pdf'
pandoc $doc -o $output `
--from gfm `
--pdf-engine xelatex `
-V CJKmainfont=SimSun `
--lua-filter=.\Builder\pandoc-wrap-tables.lua `
--include-in-header=.\Builder\pandoc-header-includes.tex
}
Write-Host "All PDFs generated successfully!"使用：
.\build-all.ps1在Markdown中编写Mermaid代码：
graph TD
A[开始] --> B{检查条件}
B -->|是| C[执行操作]
B -->|否| D[等待]
C --> E[结束]
D --> B
运行渲染脚本后，将自动生成PNG并插入引用。
sequenceDiagram
participant 用户
participant 系统
participant 数据库
用户->>系统: 发送请求
系统->>数据库: 查询数据
数据库-->>系统: 返回结果
系统-->>用户: 显示结果
展示西门子PLC的SCL代码：
TYPE "LAF_typeSequenceCommands"
STRUCT
setAutomaticMode : Bool; // Set to Automatic Mode
setSingleStepMode : Bool; // Set to Single Step Mode
off : Bool; // Turn sequence off
initialize : Bool; // Go to IDLE step
start : Bool; // Start condition
END_STRUCT;
END_TYPE
FUNCTION_BLOCK "LAF_SequenceControl"
VAR_INPUT
commands : "LAF_typeSequenceCommands";
enable : Bool;
END_VAR
VAR_OUTPUT
status : "LAF_typeSequenceStatus";
error : Bool;
END_VAR
BEGIN
// Sequence control logic here
IF commands.initialize THEN
currentStep := 0;
END_IF;
END_FUNCTION_BLOCK支持多行表头和长内容自动换行：
| 功能块名称 | 类型 | 描述 | 主要功能 |
|---|---|---|---|
| LAF_ControlSclSequence | FB | 序列控制功能块 | 实现自动化流程的步进控制，支持自动/手动模式切换 |
| LBC_MotorStarterCn | FB | 电机启动器连接 | 电机启动、停止和状态监控 |
| LBC_TwoWayActuatorCn | FB | 双向执行器控制 | 阀门或执行器的开关控制 |
在Markdown中引用网络图片：
运行渲染脚本后，将自动下载并转换为：
欢迎对本项目做出贡献！以下是参与方式：
如果您发现bug或有功能建议：
- 在 GitHub Issues 中搜索是否已有相关问题
- 如果没有，创建新Issue，详细描述问题或建议
- 提供复现步骤、错误信息或期望行为
- Fork本仓库
- 创建特性分支：
git checkout -b feature/your-feature - 提交更改：
git commit -am 'Add some feature' - 推送到分支：
git push origin feature/your-feature - 创建Pull Request
- 修正拼写或语法错误
- 添加更多使用示例
- 改进说明的清晰度
- 翻译为其他语言
本项目采用 MIT License 开源许可证。
这意味着您可以：
- ✅ 自由使用本软件用于商业或非商业目的
- ✅ 修改源代码以满足您的需求
- ✅ 分发原始或修改后的版本
- ✅ 将本软件纳入您的项目
唯一的要求是：
- 📋 在所有副本中保留原始版权声明和许可声明
详细信息请查看 LICENSE 文件。
本项目的实现离不开以下优秀的开源项目和社区：
- Pandoc - 由 John MacFarlane 开发的通用文档转换工具
- Mermaid - 强大的图表和可视化工具
- XeLaTeX - 支持Unicode和现代字体的LaTeX引擎
- MiKTeX - Windows平台的TeX/LaTeX发行版
- AI代码生成社区 - 推动了自动化文档需求
- 工业自动化社区 - 提供了SCL/PLC编程的实践经验
- 开源社区 - 分享精神和协作文化
- 🐛 问题反馈：GitHub Issues
- 💬 讨论交流：GitHub Discussions
- 📧 邮件联系：通过GitHub个人资料联系