Md Converter

MD转换器

版本： 2.1.0\ 状态： 生产就绪

使用YAML前体、严格验证、智能分节和专业Word样式将Markdown文件转换为DOCX、XLSX和PPTX格式。包括CLI和MCP（模型上下文协议）服务器接口。

______________________________________________________________________

为什么这很重要：启用IDE优先咨询

创新

虽然大多数顾问在传统的办公套件（Word、Excel、PowerPoint）中工作，并从ChatGPT或Copilot复制粘贴，但有一个 更有效的方法 等待解锁：

在人工智能的帮助下，完全在IDE中工作，然后自动生成客户端可交付成果。

当前的咨询现实

标准工作流程（2024-2025）：

1. 用Word或PowerPoint书写
2. 从ChatGPT/Copilot复制粘贴
3. 手动格式化和清理
4. 通过文件名进行版本控制
5. 通过电子邮件附件进行协作

限制：

• 工具之间的上下文切换会中断流程
• 手动格式化很耗时
• 版本控制混乱
• 人工智能辅助是分散的

IDE第一选择

该工具支持一种新方法：

• 用Markdown思考和写作 -干净、版本控制、基于Git的协作
• 利用嵌入式人工智能 -Cursor中的Claude在您的工作流程中提供实时帮助
• 纯文本工作 -快速、轻便、强大
• 单一事实来源 -Markdown为主，生成输出
• 保持流畅 -无需切换到办公应用程序

挑战

客户和利益相关者需要 传统格式 （Word、Excel、PowerPoint）：

• 行政简报需要Word文档
• 财务模型需要Excel工作簿
• 演示文稿需要PowerPoint演示文稿

手动转换会破坏IDE工作流程并浪费时间。

解决方案：MD转换器MCP

从IDE到客户端交付成果的无缝桥梁：

1. 在Markdown中工作 -完整的IDE功能、AI辅助、版本控制
2. 在YAML中添加元数据 -专业文档属性
3. 一个命令转换 -即时专业Word/Excel/PowerPoint
4. 内置验证 -质量保证确保一致性
5. 智能排除 -系统文件、注释、参考文献保留在markdown中

结果： 你保持流畅，客户得到专业的交付成果。

为什么这种方法更快

传统工作流程：

• AI工具中的草稿→ 复制到Word→ 格式→ 审查→ 修改（在Word中重复）

IDE第一个工作流程：

• 使用AI在IDE中起草→ 在IDE中使用AI进行修改→ 转换→ Done

优势：

• ✅ 所有工作的单一环境
• ✅ AI上下文在整个文档生命周期中持续存在
• ✅ 内置版本控制（Git）
• ✅ 自动应用一致的格式
• ✅ 无需手动复制粘贴
• ✅ Markdown是可移植的，面向未来

现实世界咨询示例

挑战： 为企业客户提供全面的战略规划

• 20多份规划文件，涵盖战略、架构、交付、预算
• 高管决策执行简报
• 多年期方案的财务模式
• 需要专业格式（公司分类、适当的元数据）

解决方案：

• 所有计划都在Markdown中完成，并在IDE中借助人工智能
• YAML是分类、版本和作者的首要问题
• 单一命令： md-convert "**/*.md" → 15 DOCX+1 XLSX
• 智能排除参考材料和系统文件
• 独立格式化的主要边界处的分段
• 与客户端模板兼容的专业Word样式

结果：

• 计划在几天内完成，而不是几周
• 所有文档均采用专业格式
• 跨交付成果的一致元数据
• 已准备好执行分配

______________________________________________________________________

特性

🚀 2.1.0版本增强功能

YAML前端支持

• 14个元数据字段（格式、标题、作者、日期、分类、版本、状态等）
• 自动映射到Word/Excel/PowerPoint中的文档属性
• 格式检测（docx、xlsx、pptx或其组合）
• 文档类型分类（文档、电子邮件、参考、注释、系统）

严格的文档验证

• 标题层次结构验证（无跳过级别）
• 表结构一致性检查
• 空航向检测
• 元数据完整性警告
• 可选的 --strict 生产文件模式

智能分段断路器

• DOCX： section_breaks: auto 仅创建##H2之前的部分（主要边界）
• PPTX： slide_breaks: h1|h2|hr 控制幻灯片创建
• 减少不必要的分段中断
• 启用独立的节格式

智能排除规则

• 基于路径：自动排除README、/notes/、/references/
• 前件： convert: false 或 document_type: email|reference|note|system
• 更清洁的批量转换
• 在输出中明确跳过原因

专业单词样式

• 内置样式：普通、标题1-6、列表段落
• 字符样式：强（粗体），强调（斜体）
• 模板兼容
• 易于批量重新格式化

已修复编号列表

• 正确的单词编号配置
• 顺序编号（1、2、3…）
• 不再有DOCX损坏

XLSX富文本

• 粗体文本(**text**)在Excel中正确呈现
• 斜体文本(*text*)正确渲染
• 单元格中的混合格式可以正常工作

📄 多种输出格式

• 文档：具有正确格式、标题、表格、列表和代码块的Word文档
• XLSX 文件：具有公式支持、数据类型检测和格式设置的Excel电子表格
• 演示文稿：具有自动幻灯片布局的PowerPoint演示文稿

🔢 Excel公式支持

• 转换 {=FORMULA} Markdown表中的语法到实际的Excel公式
• 支持60多种Excel函数（SUM、AVERAGE、IF、VLOOKUP等）
• 自动数据类型检测（数字、日期、布尔值、文本）
• 细胞参考验证

🤖 双接口

• 命令行界面：用于批处理的命令行工具
• MCP服务器：与Cursor中的Claude等人工智能助手集成

🎨 格式选项

• 可定制的字体和大小
• Excel中列的自动宽度
• 冻结的标题行
• 演示文稿的浅色/深色主题
• 澳大利亚日期格式（日/月/年）

______________________________________________________________________

安装

# Clone or navigate to the repository
cd /path/to/md_converter

# Install dependencies
npm install

# Build the project
npm run build

______________________________________________________________________

快速开始

1.在Markdown中添加前置内容

---
format: docx
title: "Executive Brief - AI Strategy"
author: "Dale Rogers"
date: "2025-11-10"
classification: "OFFICIAL"
version: "1.0"
status: final
keywords: ["AI", "strategy", "executive"]
section_breaks: auto
---

# Executive Brief

Your content here...

2.转换为Word

md-convert document.md --format docx

3.审查输出

• 打开生成的 .docx 文件
• 检查文件→ Info → 元数据的属性
• 在主页中验证样式→ 样式窗格
• 检查分段中断（查看→ 草稿模式）

______________________________________________________________________

YAML前体参考

必填字段

format: docx              # docx, xlsx, pptx, or combinations
title: "Document Title"   # Document title (used in properties)

扩展字段（推荐）

author: "Your Name"                      # Creator/author name
date: "2025-11-10"                      # Document date (YYYY-MM-DD)
classification: "OFFICIAL"               # Security classification
version: "1.0"                          # Version number
status: final                           # draft|review|approved|final
description: "Brief description"         # Document description (250个字符\
⚠️ 文档中没有H1标题\
⚠️ 没有语言标记的代码块\
⚠️ 空列表

### 查看验证输出

Converting: document.md ⚠ Warnings: • Recommended field missing: author • Recommended field missing: version 📄 Executive Brief (docx) v1.0 - final ✓ DOCX: document.docx

______________________________________________________________________

## 发展

Install dependencies

npm install

Build

npm run build

Run CLI in dev mode (with TypeScript)

npm run dev -- input.md --format docx

Start MCP server in dev mode

npm run serve

Type check (without building)

npm run type-check

Watch mode (auto-rebuild on changes)

tsc --watch

______________________________________________________________________

## 项目结构

md_converter/ ├── src/ │ ├── core/ │ │ ├── parsers/ │ │ │ ├── markdown.ts # Markdown parsing │ │ │ ├── frontmatter-parser.ts # YAML front matter │ │ │ ├── table-parser.ts # Table processing │ │ │ └── formula-parser.ts # Formula validation │ │ ├── converters/ │ │ │ ├── docx-converter.ts # Word generation │ │ │ ├── xlsx-converter.ts # Excel generation │ │ │ ├── pptx-converter.ts # PowerPoint generation │ │ │ └── section-rules.ts # Section/slide break logic │ │ └── validators/ │ │ └── document-validator.ts # Document validation │ ├── mcp/ │ │ ├── server.ts # MCP server │ │ └── tools.ts # MCP tool definitions │ ├── cli/ │ │ └── index.ts # CLI interface │ └── index.ts # Main exports ├── examples/ │ ├── frontmatter-template.md # Template for new docs │ ├── sample.md # Formula example │ └── presentation.md # Presentation example ├── FRONTMATTER.md # Complete specification ├── CHANGELOG.md # Version history ├── README.md # This file ├── package.json # Dependencies └── tsconfig.json # TypeScript config

______________________________________________________________________

## 技术细节

**Markdown解析：** `markdown-it` -基于AST的强大解析

**DOCX生成：** `docx` 库-专业Word文档，包括：

- 内置单词样式（普通、标题1-6、列表段落、强、强调）
- 列表的正确编号配置
- 独立格式化的部门管理
- 文档属性（标题、作者、主题、关键字、分类）

**XLSX代：** `exceljs` -Excel工作簿，包含：

- 原生公式支持（实际Excel公式，而非文本）
- 富格文本格式（单元格中粗体、斜体）
- 多个工作表（每个标记表一个）
- 自动调整列的宽度和冻结的标题
- 文档属性

**PPTX代：** `pptxgenjs` -PowerPoint演示文稿，包括：

- 灵活的幻灯片布局
- 主题支持（亮/暗）
- 表格和要点
- 文档属性

**YAML解析：** `js-yaml` -行业标准的YAML解析器

**MCP集成：** `@modelcontextprotocol/sdk` -官方模型上下文协议SDK

______________________________________________________________________

## 局限性

### 按格式支持公式

|格式|公式支持|说明|
|--------|----------------|-------------|
| **XLSX 文件** | ✅ **全力支持** |公式转换为自动计算的实际Excel公式|
| **文档** | ❌ 纯文本|以纯文本显示的公式（Word不支持单元格计算）|
| **演示文稿** | ❌ 纯文本|公式在表单元格中以纯文本显示|

**重要提示：** 对于工作公式，请始终使用 `format: xlsx`.

### 其他限制

- **图像：** 尚未支持（计划用于v2.2）
- **复杂嵌套列表：** 仅限于单层列表
- **非常大的桌子：** 可能需要在PPTX中手动调整
- **自定义Word模板：** 尚不支持（仅使用内置样式）
- **美人鱼图：** 不支持（呈现为代码块）

______________________________________________________________________

## 故障排除

### “未找到表”错误

**解决方案：** XLSX格式需要标记表。在文档中至少添加一个表。

### Excel中未显示粗体文本

**解决方案：** 使用v2.1.0或更高版本。早期版本有一个富文本格式错误（现已修复）。

### 编号列表在Word中不起作用

**解决方案：** 使用v2.1.0或更高版本。早期版本缺少编号配置（现已修复）。

### Word中到处都有分节符

**解决方案：** 使用 `section_breaks: auto` 而不是 `section_breaks: all`自动模式仅在主要边界（##H2之前）创建部分。

### 转换过程中跳过的文件

**解决方案：** 检查文件是否符合排除规则：

- 是README.md吗？
- 它在/notes/或/references/目录中吗？
- 前件有没有 `convert: false`?
- 前件有没有 `document_type: email|reference|note|system`?

______________________________________________________________________

## 贡献

这是一个活跃的项目。欢迎投稿！

**贡献领域：**

- 图像支持
- 自定义Word模板
- 多级列表支持
- 美人鱼图渲染
- 附加公式函数
- 增强的验证规则

______________________________________________________________________

## 更新日志

看 `CHANGELOG.md` 版本历史。

______________________________________________________________________

## 许可证

麻省理工学院

______________________________________________________________________

## 作者

戴尔·罗杰斯\
服务设计负责人\
2025

______________________________________________________________________

## 致谢

专为现实世界的咨询需求而设计，通过在企业和政府咨询项目中的生产使用进行改进。

开发用于支持 **IDE优先咨询方法**，使顾问能够利用人工智能的帮助，同时保持专业的客户交付成果。

______________________________________________________________________

**注：** 本项目全程使用澳大利亚英语拼写和日期格式（DD/MM/YYYY）。