# MarkdownManager **Repository Path**: birdman1992/markdown ## Basic Information - **Project Name**: MarkdownManager - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2025-10-28 - **Last Updated**: 2026-07-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: Pandoc, markdown转pdf ## README # Markdown文档格式转换工具 这个项目提供了一套完整的解决方案，用于将Markdown文档自动转换为HTML、Word和PDF格式，特别针对中文文档进行了优化。系统还提供了自动霄镜式SVG嚾片处理，克服了不修改输入文件的难题。 ## 功能特点 - **一键转换所有文件**：自动扫描`input/`目录中的所有Markdown文件 - **多格式输出**：支持HTML、Word(.docx)和PDF格式输出 - **中Brush支持**：完美支持中文显示，包括中文字体配置 - **SVG嚾片自动化**：自动转换SVG为PDF，无需修改输入文件 - **样式定制**：提供CSS、Word模板咏LaTeX模板来自定义输出样式 - **表格样式**：专门的Lua过滤器用于美PDF中的表格样式 - **自动化脚本**：一键运行的批处理脚本，简化转换流程 ## 文件结构 ``` project/ ├── Convert-All.ps1 # 主转换脚本（所有格式） ├── Convert-ToHtml.ps1 # HTML 转换脚本 ├── Convert-ToWord.ps1 # Word 转换脚本 ├── Convert-ToPdf.ps1 # PDF 转换脚本 ├── ConvertCommon.psm1 # 共享 PowerShell 模块 ├── convert_svg_to_pdf.py # SVG 转 PDF 工具 ├── merge_cover.py # Word 封面/声明页/尾页合并工具 ├── merge_pdf.py # PDF 封面/声明页/尾页合并工具 ├── resources/ # 模板和样式资源 │ ├── pdf_template.latex # PDF LaTeX 模板 │ ├── style.css # HTML 样式 │ ├── example.docx # Word 参考文档 │ └── table_filter.lua # 表格样式过滤器 ├── filters/ # Pandoc Lua 过滤器 │ ├── svg_to_pdf.lua # SVG→PDF 过滤器 │ └── word_size_control.lua # Word 大小控制过滤器 ├── vendor/ # 离线依赖 │ ├── pypdf2/ # PyPDF2 库（支持 Python 3.8/3.11/3.12） │ └── powershell-yaml/ # PowerShell YAML 解析模块 ├── docs/ # 文档 │ ├── README.md # 文档导航 │ ├── getting-started.md # 快速入门 │ ├── user-guide.md # 用户指南 │ ├── advanced-features.md # 高级特性 │ ├── troubleshooting.md # 故障排查 │ ├── changelog.md # 版本历史 │ └── development.md # 开发者文档 ├── README.md # 项目主文档 ├── CHANGELOG.md # 版本历史 └── ... ``` **工作空间目录**（自动创建）： ``` %USERPROFILE%\MarkdownConverterWorkspace\ ├── config.docx # 文档模板（封面、声明页、尾页） ├── config.yaml # 样式配置文件 ├── config.pdf # 模板 PDF（自动从 config.docx 生成） ├── input/ # 输入 Markdown 文件 │ ├── example.md # 转换示例文档（包含所有已支持的语法元素） │ └── images/ # 图片文件（SVG、PNG 等） └── output/ # 输出文件（HTML、Word、PDF） ``` `input/example.md` 是转换功能的参考示例，涵盖了当前支持的所有 Markdown 语法元素（标题、文本样式、列表、表格、代码块、图片、公式、交叉引用等）。如需支持新的内容格式，请联系开发者。 ## 环境要求 1. **Pandoc**：文档转换工具 2. **LaTeX发行版**（可选）：用于生成PDF文档（推荐使用MiKTeX或TeX Live） 3. **Python 3.8+**：用于 SVG 转换、封面合并等辅助功能 4. **WPS Office / Microsoft Word / LibreOffice**（可选）：用于将 config.docx 转换为 PDF 模板，生成高保真封面页 ## 使用方法 ### 快速开始 将 Markdown 文件放置于工作空间的 `input/` 目录中，然后运行 PowerShell 脚本： ```powershell # 转换所有格式（HTML、Word、PDF） .\Convert-All.ps1 # 或仅转换特定格式 .\Convert-ToHtml.ps1 .\Convert-ToWord.ps1 .\Convert-ToPdf.ps1 ``` 转换后的文件将保存在 `output` 目录中。 ### 详细文档 详细的使用教程、常见问题和高级功能，请参考： - **[快速入门指南](docs/getting-started.md)** - 环境配置和基本使用 - **[用户指南](docs/user-guide.md)** - 详细的功能说明 - **[高级特性](docs/advanced-features.md)** - 交叉引用、样式定制等 - **[故障排查](docs/troubleshooting.md)** - 常见问题解决方案 - **[开发者文档](docs/development.md)** - 项目架构和开发指南 ## 文档模板（config.docx） 工作空间中的 `config.docx` 是文档模板文件，用于为 Word 和 PDF 输出提供统一的封面、声明页和尾页。 ### 模板结构 `config.docx` 应包含以下页面，按顺序排列： | 页面 | 说明 | |------|------| | 封面页 | 产品/项目封面，包含标题、版本号、公司信息等 | | 声明页 | 版权声明、版本记录等 | | 目录页 | 目录占位（转换时会自动生成实际目录） | | 尾页 | 公司联系方式、地址等信息 | ### 工作原理 **Word 输出**：`merge_cover.py` 直接从 `config.docx` 的 XML 结构中提取封面、声明页和尾页，合并到 Pandoc 生成的 Word 文档中。 **PDF 输出**： 1. 通过 WPS Office / Word / LibreOffice 的 COM 自动化将 `config.docx` 转换为 `config.pdf` 2. `merge_pdf.py` 从 `config.pdf` 中提取第 1 页（封面）、第 2 页（声明）和目录之后的首页（尾页） 3. 将提取的页面与 Pandoc 生成的内容 PDF 合并，最终顺序为：封面 → 声明 → 正文内容 → 尾页 ### 缓存机制 `config.pdf` 会缓存在工作空间目录中。当 `config.docx` 被修改后，下次运行转换脚本时会自动重新生成 `config.pdf`。 ### 注意事项 - 如果未放置 `config.docx`，转换脚本会跳过封面合并，仅输出正文内容 - PDF 封面合并需要系统安装 WPS Office、Microsoft Word 或 LibreOffice 中的任意一个 - Word 封面合并仅依赖 Python，无需额外办公软件 ## Markdown语法标准 为了确保文档的一致性和可转换性，建议采用统一的Markdown语法标准： ### 基础语法标准 - 采用 **[GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/)** 作为主要编写标准 - 遵循 **[CommonMark规范](https://spec.commonmark.org/)**，确保语法的明确性和无歧义性 - 使用 **[Pandoc Markdown扩展](https://pandoc.org/MANUAL.html#pandocs-markdown)**，支持更多格式化选项 ### Pandoc Markdown扩展 Pandoc在标准Markdown基础上提供了丰富的扩展功能，包括但不限于： - **表格**：支持多种表格语法，包括简单的表格和复杂的表格 - **脚注**：使用`[^1]`语法添加脚注引用，使用`[^1]: 脚注内容`定义脚注 - **定义列表**：支持定义列表语法，用于术语解释 - **任务列表**：支持GitHub风格的任务列表 - **删除线**：使用`~~删除线文本~~`语法 - **上标和下标**：使用`^上标^`和`~下标~`语法 - **数学公式**：支持LaTeX数学公式语法 - **引文**：支持引文和参考文献格式 - **交叉引用**：支持表格、公式、图片等元素的交叉引用 ### 标准化建议 具体实施过程中，建议可以给出一个[示例](docs/sample_document.md)，列举markdown中所支持的元素，从开发的角度来看， markdown语法是比较简单清晰，有一个示例的话，是易于上手的。 ### 交叉引用 项目支持表格、公式和图片的交叉引用功能： - **表格引用**：使用 `Table: 表格标题 {#tbl:label}` 语法定义带标签的表格，使用 `见表 @tbl:label` 进行引用 - **公式引用**：在公式内使用 `\label{eq:label}` 定义标签，使用 `见式 @eq:label` 进行引用 - **图片引用**：使用 `![标题](路径){#fig:label}` 语法定义带标签的图片，使用 `见图 @fig:label` 进行引用 详细使用方法请参考[交叉引用使用指南](docs/cross_reference_guide.md)。 ## 推荐编辑工具 为了提高Markdown文档编写效率，推荐使用以下编辑器： ### 技术团队推荐 **VS Code + Markdown插件** 可以使用插件：Markdown Image,Markdown Table,Markdown All in One - 免费且功能强大 - 丰富的插件生态系统 - 支持实时预览和语法高亮 - 与Git集成良好，适合团队协作 - 图片可以粘贴引入 - 表格可以从TSV格式化生成 - 内网开发环境也是vscode，开发人员写markdown会比较方便 **Typora** - 所见即所得的Markdown编辑体验 - 界面简洁美观 - 支持多种导出格式 - 适合专注写作 - 不用太多关注markdown语法 - 付费软件 **Obsidian** - 专注于知识管理 - 强大的双向链接功能 - 适合构建个人知识库 ### 企业环境推荐 - **Confluence**：企业级协作平台 - **Notion**：多功能笔记和项目管理工具 - **Web IDE**：基于浏览器的集成开发环境 这些方案多用于协作编辑。 ## 表格样式定制 项目包含一个Lua过滤器(`docs/table_filter.lua`)，用于自定义PDF中的表格样式： - 表头背景色：#508AC8，文字颜色白色 - 内容格子背景色：无色(透明) - 表格行高：1.2cm - 表格边框：完整边框 - 文字对齐：水平和垂直居中 ## 许可证 本项目为开源项目，可根据需要自由使用和修改。