pickle-an/md-to-docx-skill/skill
Claude Code and agent skill by pickle-an/md-to-docx-skill
- community
Checking that the SKILL.md file is still in the repository.
将 Markdown 文件转换为格式化的 Word 文档。当用户想要将 .md 转换为 .docx、从 Markdown 创建 Word 文档或提及文档转换时调用此技能。
Install
npx vskill@latest install pickle-an/md-to-docx-skill/skillSKILL.md
Markdown 转 Word 文档转换器
本技能将 Markdown 文件转换为专业格式的 Word 文档(.docx)。
何时调用
在以下情况下调用此技能:
- 用户想要将 Markdown 文件转换为 Word 文档
- 用户要求从 Markdown 内容创建 Word 文档
- 用户提及
.md到.docx的转换 - 用户需要格式化的文档输出
处理流程
功能特性
1. 自动版本管理
技能自动管理输出文件的版本号:
| 场景 | 输入文件 | 输出文件 | |
|---|---|---|---|
| 文件名无版本号 | document.md | document_V1.docx、document_V1_normalized.md | |
| 文件名含版本号 | document_V3.md | document_V4.docx、document_V4_normalized.md | |
| 目录中已有 V1 | document.md | document_V2.docx、document_V2_normalized.md |
版本规则:
- 如果输入文件名包含版本号(如
_V3),则从该版本号递增 - 如果文件名无版本号,则扫描目录中已有版本并递增
- 版本格式:
_V{n},其中 n 为整数(V1、V2、V3...) .docx和_normalized.md文件使用相同的版本号
2. Markdown 格式规范化
转换前,技能会自动规范化 Markdown 格式问题:
| 问题类型 | 示例 | 修复 | |||
|---|---|---|---|---|---|
| 未闭合的代码块 | `python 无闭合 | 自动添加闭合 ` | |||
| 标题后无空格 | ###标题 | →### 标题 | |||
| 标题中的中文数字 | ## 一、核心原理 | →## 1. 核心原理 | |||
| 标题中的中文数字 | ### (一)技术细节 | →### (1) 技术细节 | |||
| 无序列表无空格 | -项目 | →- 项目 | |||
| 有序列表无空格 | 1.项目 | →1. 项目 | |||
| 分隔线变体 | -- 或 ---- | →--- | |||
| 不匹配的粗体标记 | **只有开头 | 移除无效标记 | |||
| 不匹配的斜体标记 | *只有开头 | 移除无效标记 | |||
| 缺少表格分隔行 | 表格无` | --- | ` | 自动添加分隔行 | |
| 表格列数不一致 | 行的列数不同 | 自动填充/截断 | |||
| 多个连续空行 | 3+ 个连续空行 | 压缩为 1 个 | |||
| 标题前缺少空行 | 文本直接在标题前 | 添加空行 | |||
| 有序列表间距 | 列表项之间的空行 | 保留(不移除) | |||
| 段落首行空格 | 带首行空格的文本 | 移除首行空格 | |||
| 段落间空行 | 段落之间的单个空行 | 移除(清理) |
中文数字转换: 技能自动将标题中的中文数字序列转换为阿拉伯数字:
- 支持:一、二、三、四、五、六、七、八、九、十(至二十)
- 模式 1:
一、→1.(中文标点) - 模式 2:
(一)→(1)(括号形式) - 适用于所有标题级别(# ~ ######)
有序列表间距: 有序列表项之间的空行会被智能保留以保持文档可读性:
- 如果两个编号列表项之间存在空行,该空行将被保留
- 这允许列表项内容有更好的视觉分隔
- 示例:
1. 项目 1→(空行)→2. 项目 2将保留间距
空行管理: 技能根据上下文智能管理空行:
- 移除:普通段落之间的空行(清理以获得更好的格式)
- 保留:特殊元素周围的空行(标题、列表、代码块、表格、分隔线)
- 保留:缩进内容周围的空行(列表项详情、嵌套项)
- 压缩:多个连续空行减少为单个
段落首行空白: 普通段落的首行空白会自动移除以防止 Word 中出现双重缩进:
- Word 文档自动为段落应用首行缩进
- Markdown 中的首行空格会造成视觉不一致
- 列表项缩进被保留(无序列表和有序列表)
- 代码块和引用块保留其格式
3. 支持的 Markdown 元素
| 元素 | 语法 | 支持程度 | |||
|---|---|---|---|---|---|
| 标题 | # ~ ###### | 完全支持 | |||
| 段落 | 纯文本 | 完全支持 | |||
| 粗体 | **文本** | 完全支持 | |||
| 斜体 | *文本* | 完全支持 | |||
| 粗体+斜体 | ***文本*** | 完全支持 | |||
| 无序列表 | - 项目 / * 项目 | 完全支持 | |||
| 有序列表 | 1. 项目 | 完全支持 | |||
| 表格 | ` | 列 | ` | 完全支持 | |
| 代码块 | `代码` | 完全支持 | |||
| 行内代码 | ` 代码 ` | 完全支持 | |||
| 链接 | [文本](url) | 完全支持 | |||
| 图片 |  | 完全支持 | |||
| 引用块 | > 引用 | 完全支持 | |||
| 分隔线 | --- | 完全支持 | |||
| 删除线 | ~~文本~~ | 完全支持 | |||
| 换行 | <br> 或 \\ | 完全支持 |
4. 文档格式规范
字体规范
| 元素类型 | 中文字体 | 英文字体 | 字号 | 说明 | |
|---|---|---|---|---|---|
| 正文 | 宋体 | Times New Roman | 12pt(小四) | 标准正文字号 | |
| 一级标题 | 宋体 | Times New Roman | 22pt(二号) | 大标题 | |
| 二级标题 | 宋体 | Times New Roman | 16pt(三号) | 章节标题 | |
| 三级标题 | 宋体 | Times New Roman | 15pt(小三) | 小节标题 | |
| 四级标题 | 宋体 | Times New Roman | 14pt(四号) | 条目标题 | |
| 五级标题 | 宋体 | Times New Roman | 14pt(四号) | 子条目标题 | |
| 代码块 | Consolas | Consolas | 9pt(小五) | 略小于正文 | |
| 行内代码 | Consolas | Consolas | 12pt(小四) | 与正文同字号 |
段落规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 首行缩进 | 0.74cm | 约两个汉字宽度 | |
| 行间距 | 1.5 倍 | 提升阅读舒适度 | |
| 段前间距 | 0pt | 保持紧凑排版 | |
| 段后间距 | 0pt | 保持紧凑排版 |
标题规范
| 标题级别 | Markdown 语法 | 字号 | 样式特点 | |
|---|---|---|---|---|
| 文档标题 | # 标题 | 22pt(二号) | 加粗、居中、可生成封面页 | |
| 一级标题 | ## 标题 | 22pt(二号) | 加粗、段前自动分页 | |
| 二级标题 | ### 标题 | 16pt(三号) | 加粗、不分页 | |
| 三级标题 | #### 标题 | 15pt(小三) | 加粗、不分页 | |
| 四级标题 | ##### 标题 | 14pt(四号) | 加粗、不分页 | |
| 五级标题 | ###### 标题 | 14pt(四号) | 加粗、不分页 |
表格规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 表格样式 | Table Grid | 带边框的标准表格 | |
| 对齐方式 | 居中 | 表格整体居中显示 | |
| 列宽 | 自动计算 | 根据内容智能分配 | |
| 表头背景 | #D9D9D9 | 浅灰色背景突出表头 | |
| 表头对齐 | 居中 | 表头文字居中对齐 | |
| 单元格对齐 | 左对齐 | 数据内容左对齐 |
代码块规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 字体 | Consolas | 等宽字体,代码清晰 | |
| 字号 | 9pt | 略小于正文 | |
| 背景色 | #F5F5F5 | 浅灰色背景区分代码 | |
| 左缩进 | 0.5cm | 突出代码块层次 | |
| 语言标签 | 斜体显示 | 如[python] |
行内代码规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 字体 | Consolas | 等宽字体 | |
| 字号 | 同正文 | 保持行高一致 | |
| 背景色 | #F0F0F0 | 浅灰背景突出显示 |
引用块规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 左边框 | #6366F1 | 紫色竖线标识 | |
| 边框宽度 | 1.5pt | 清晰可见 | |
| 左右缩进 | 1cm | 突出引用内容 | |
| 字体样式 | 斜体 | 区分引用文字 |
列表规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 左缩进 | 0.74cm × 层级 | 支持多级嵌套缩进 | |
| 行间距 | 1.5 倍 | 与正文保持一致 | |
| 无序列表符号 | • | 实心圆点 | |
| 有序列表格式 | 1. 2. 3. | 数字加点 |
分隔线规范
| 属性 | 设置值 | 说明 | |
|---|---|---|---|
| 样式 | 底部边框 | 段落下方的横线 | |
| 颜色 | #CCCCCC | 浅灰色 | |
| 段前段后间距 | 6pt | 保持适当间隔 |
封面页规范
| 元素 | 设置值 | 说明 | |
|---|---|---|---|
| 标题字号 | 22pt | 与一级标题一致 | |
| 标题样式 | 加粗、居中 | 突出文档标题 | |
| 版本信息 | 12pt、居中 | 格式:版本:V1 | |
| 日期信息 | 12pt、居中 | 格式:编制日期:2024年01月01日 | |
| 前置空行 | 3 行 | 标题上方留白 | |
| 后置空行 | 14 行 | 标题与版本信息间距 |
分页控制
| 规则 | 说明 | |
|---|---|---|
| 一级标题前分页 | 每个一级标题自动另起一页 | |
| 其他标题不分页 | 二级及以下标题保持连续 | |
| 封面页后分页 | 封面页结束后自动分页 |
使用方法
基本转换
使用自定义模板
带封面页
参数说明
| 参数 | 类型 | 必填 | 描述 | |
|---|---|---|---|---|
markdown_content | 字符串 | 是 | Markdown 文本或文件路径 | |
output_path | 字符串 | 否 | 输出 .docx 文件路径 | |
template_path | 字符串 | 否 | 自定义 .docx 模板路径 | |
version | 字符串 | 否 | 封面页版本号(未提供则自动生成) | |
date | 字符串 | 否 | 封面页日期 | |
normalize | 布尔值 | 否 | 启用格式规范化(默认:true) | |
save_normalized | 布尔值 | 否 | 保存规范化后的 MD 文件(默认:true) | |
use_versioning | 布尔值 | 否 | 启用自动版本编号(默认:true) |
实现原理
技能使用 Python 脚本,逻辑如下:
步骤 0:版本管理(version_manager.py)
步骤 1:格式规范化(markdown_normalizer.py)
步骤 2:解析 Markdown(md_to_docx.py)
步骤 3:生成 Word 文档
输出文件
转换后,生成以下文件:
| 文件 | 描述 | |
|---|---|---|
document_V{n}.docx | 带版本号的最终 Word 文档 | |
document_V{n}_normalized.md | 带版本号的规范化 Markdown |
版本号示例:
- 首次转换:
document_V1.docx、document_V1_normalized.md - 第二次转换:
document_V2.docx、document_V2_normalized.md - 带版本输入:
document_V3.md→document_V4.docx
模板支持
使用自定义模板
如果提供了模板:
- 继承页面设置(边距、纸张大小)
- 继承样式定义(标题 1-6、正文)
- 添加新内容前清除模板内容
内置样式(无模板)
本 Skill 可独立运行,无需外部模板文件。
如果未提供模板或模板文件不存在:
- 自动创建空白文档
- 使用默认页面设置(A4,2.54cm 边距)
- 以编程方式创建样式
- 应用一致的格式
这意味着本 Skill 可以在任何安装了 Python 和 python-docx 的环境中独立运行,无需依赖外部模板文件。
示例
示例 1:格式规范化
输入(含问题):
规范化输出:
示例 2:简单转换
输入:
输出:格式化的 Word 文档,具有正确的标题层级和项目符号列表。
示例 3:带表格
输入:
输出:带格式化表格的 Word 文档,表头行为灰色背景。
示例 4:带代码块
输入:
npm install package-name
输出:带等宽字体代码块的 Word 文档。
错误处理
- 无效 Markdown:记录警告,继续部分解析
- 模板缺失:回退到内置样式
- 文件未找到:返回清晰的错误消息
- 权限错误:建议替代输出路径
- 格式问题:在规范化阶段自动修复
依赖
- Python 3.x
- python-docx 库
模块文件
| 文件 | 描述 | |
|---|---|---|
md_to_docx.py | 主转换脚本 | |
markdown_normalizer.py | Markdown 格式规范化 | |
version_manager.py | 自动版本编号 | |
create_template.py | 模板生成脚本(可选) | |
template.docx | 默认 Word 模板(可选) |
说明:
template.docx是可选的模板文件,如果存在则使用,不存在则自动创建空白文档create_template.py可用于重新生成符合格式规范的模板文件- 本 Skill 可完全独立运行,无需外部依赖
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskill/SKILL.md
Popularity
- Repository stars
- 66
- Repository forks
- 8
- 7-day trend score
- 21
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/pickle-an/md-to-docx-skill/skill)