# Markdown转换成文档

**Repository Path**: BonizLee/convert-markdown-to-document

## Basic Information

- **Project Name**: Markdown转换成文档
- **Description**: 将markdown格式文章草稿按照论文格式要求生成对应work文档。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-29
- **Last Updated**: 2026-06-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# convert-markdown-to-document（md2docx）

将 Markdown 文档按指定 JSON 排版样式转换为 Word（.docx）。支持 CLI 与 GUI（PyQt）两种运行方式，并提供一键打包为单文件 exe（无 Python 环境可运行）。

## 功能概览

- Markdown 解析：标题（#~######）、普通段落、图片、代码块、pipe 表格
- 排版样式：通过 `format.json` 统一配置（字体、字号、行距、段前段后、缩进、对齐等）
- 论文增强能力：
  - 一级标题自动新建分节（新页）
  - 页眉：左侧为 `format.json` 的 `title`，右侧为一级标题去掉序号后的文字；每节页眉不继承前节
  - 页脚：居中页码（PAGE）
  - 表格三线表
  - 图片居中
  - 表格单元格垂直居中
  - `图X-X` / `表X-X` 识别为 `image_caption`
  - `**加粗**` 识别为 `keywords` 并应用 `styles.keywords` 样式
  - 目录页：插入 TOC 域（目录级别到二级标题，打开 Word 后更新域生成目录）

## 目录结构

- `md2docx/`：核心包（GUI/CLI 共用）
  - `converter.py`：转换编排（读取文件、解析、渲染）
  - `markdown_parser.py`：Markdown 解析（生成 Block 列表）
  - `docx_renderer.py`：Block → docx 渲染
  - `docx_format.py`：Word 细节与样式应用（页眉页脚、边框、分节、页码域、TOC 域等）
  - `patterns.py`：正则配置加载（默认 + `md_regex.json` 自动发现）
  - `gui.py`：PyQt GUI
  - `cli.py`：命令行入口
- `md_regex.json`：Markdown/规则匹配配置（运行时自动加载）
- `gdpepe_format.json`：样式示例（可作为模板修改）
- `ico/favicon.ico`：GUI 图标与 exe 图标
- `build_md2docx_gui.bat`：PyInstaller 单文件打包脚本

## 环境与依赖

- Python 3.10+（源码运行时需要）
- 依赖见 `requirements.txt`
  - `python-docx`
  - `PyQt6`

安装依赖：

```bash
pip install -r requirements.txt
```

## GUI 使用

启动 GUI：

```bash
python -m md2docx.gui
```

操作流程：

1. 选择 Markdown 文件
2. 选择排版样式 `format.json`
3. 输出 docx 可不填（默认与 md 同名），也可选择保存路径
4. 点击“开始转换”

## CLI 使用

命令行参数顺序：

```bash
python -m md2docx.cli <input.md> <format.json> <output.docx>
```

## 配置说明

### 1）样式文件（format.json）

样式文件为 JSON，关键字段：

- `title`：用于页眉左侧
- `meta.page.margins_cm`：页边距
- `styles`：各类元素样式（按 `paragraph` 段落级、`run` 字符级拆分）

常用样式节点（示例中已包含）：

- `styles.heading["1"~"6"]`
- `styles.paragraph`
- `styles.code`
- `styles.table`
- `styles.image`
- `styles.image_caption`
- `styles.keywords`
- `styles.references`
- `styles.header`
- `styles.footer`

字号填写使用 `font_size_pt`（单位 pt）。例如小五一般为 9pt。

### 2）正则配置（md_regex.json）

程序会自动加载 `md_regex.json`，查找顺序：

1. 环境变量 `MD2DOCX_REGEX_PATH`
2. 当前工作目录 `.\md_regex.json`
3. 可执行入口目录下的 `md_regex.json`
4. 打包后 PyInstaller 的运行时目录（`sys._MEIPASS`）

可配置项：

- `heading`、`image`、`code_fence`、`caption`、`table_separator_cell`
- `references_headings`：一级标题哪些文字按 `references` 样式处理（如：参考文献、致谢、附录、前言）

## 打包为单文件 exe（绿色版）

使用 PyInstaller 的 `--onefile` 打包（包含运行库与依赖，目标机器无需安装 Python）。

运行脚本：

```bat
build_md2docx_gui.bat
```

产物：

- `dist\md2docx_gui.exe`

说明：

- 图标使用 `ico\favicon.ico`
- `md_regex.json` 与 `ico\favicon.ico` 会作为资源打进 exe，运行时从 PyInstaller 解包目录读取

## 目录（TOC）注意事项

目录页使用 TOC 域插入。Word 是否自动更新目录与本机 Word 安全策略有关：

- 若打开 docx 后目录为空：在 Word 中右键目录 → “更新域/更新目录” → “更新整个目录”

## 常见问题

1. 图片路径找不到  
   - Markdown 图片路径为相对路径时，按 md 文件所在目录解析。

2. 打包后找不到 `md_regex.json`  
   - 已支持在打包运行时目录（`sys._MEIPASS`）读取；确认打包命令包含 `--add-data "md_regex.json;."`。