docx-formatter-cn 使用文档

📦 安装

从源码安装

git clone https://github.com/vajhXajhcv/docx-formatter-cn.git
cd docx-formatter-cn
pip install -e .

依赖要求

Python 3.10+
python-docx ≥ 1.1.0
latex2mathml ≥ 3.79.0
lxml ≥ 5.0.0
PyYAML ≥ 6.0
PySide6 ≥ 6.6.0（GUI 可选）

🌐 在线工具

如果不想安装 Python 环境，可以直接在浏览器里使用在线版：

在线 Markdown 转 Word（论文排版）

在线版基于 Pyodide 在本地浏览器内运行，Markdown 内容不会上传到服务器。当前支持：

中文学术模板：课程论文、毕业论文、数学建模、公文、武汉理工毕业设计
英文期刊 / 预印本近似格式：arXiv Preprint、Nature、Science、IEEE Transactions（单栏近似）、APA Manuscript
LaTeX 公式自动转为 Word 原生 OMML 公式、三线表、标题自动编号

使用步骤

打开 /tools/md2docx；
在左侧编辑器粘贴 Markdown，选择目标模板；
点击「开始转换」，首次使用会下载约 10-20 MB 的 Python 运行环境；
转换完成后点击「下载 Word 文档」保存结果。

提示：在线版暂不支持引用本地图片文件；如需批量转换、自定义学校模板或图片路径解析，请使用桌面 Pro 版。

🖥️ 命令行使用

Markdown 转 Word

python -m docx_formatter.cli convert input.md -o output.docx -t 课程论文

批量转换

python -m docx_formatter.cli batch input_dir/ -o output_dir/ -t 课程论文

修正现有 Word

python -m docx_formatter.cli format input.docx -o output.docx -t 毕业论文 --add-toc

查看模板信息

python -m docx_formatter.cli info -t 毕业论文
python -m docx_formatter.cli export-template -t 课程论文 -o template.json

常用参数

参数	说明
`-t, --template`	模板预设：课程论文 / 毕业论文 / 数学建模 / 公文
`--template-file`	自定义模板 JSON/YAML 文件
`--image-dir`	图片基础目录
`--add-toc`	添加目录（format 命令）

🐍 Python API

Markdown 转 Word

from docx_formatter import convert_markdown_to_docx

with open("论文.md", "r", encoding="utf-8") as f:
    md_text = f.read()

convert_markdown_to_docx(md_text, "output.docx", template="课程论文")

修正已有 docx

from docx_formatter import format_docx

format_docx("old.docx", "formatted.docx", template="毕业论文", add_toc=True)

📝 Markdown 语法支持

YAML Frontmatter

---
title: 论文标题
author: 作者姓名
date: 2026-05-28
abstract: 摘要内容...
keywords: [关键词1, 关键词2]
---

基础语法

语法	效果
`# 标题`	一级标题
`粗体`	粗体
`斜体`	斜体
`<u>下划线</u>`	下划线
`~~删除线~~`	删除线
`code`	行内代码

公式

行内公式：$E = mc^2$ 或 \(E = mc^2\)

块级公式：
$$E = mc^2$$

或：
\[E = mc^2\]

图片尺寸控制

![图1](images/fig1.png)
![图2](images/fig2.png =400x300)

表格

| 算法 | 时间复杂度 | 空间复杂度 |
|------|-----------|-----------|
| 快速排序 | O(n log n) | O(log n) |

其他

上标引用：[1] → 自动转为上标
超链接：[text](url)
引用块：> text
任务列表：- [x] 已完成
分页符：--- 或 <page-break>

🎨 模板系统

预设模板

模板	适用场景
课程论文	日常课程作业、小论文
毕业论文	本科/硕士毕业论文
武汉理工毕业设计	武汉理工大学毕业设计（论文）
数学建模	数学建模竞赛论文
公文	政府机关公文格式

期刊 / 预印本模板

除中文学术预设外，工具还提供若干著名英文期刊与预印本平台的近似格式，方便投稿前快速生成符合其排版惯例的 Word 稿件。

模板	说明
arXiv Preprint	arXiv 预印本通用单栏格式：A4、1 英寸边距、12pt Times New Roman
Nature	Nature 系列期刊近似格式：较窄边距、10pt Arial、1.5 倍行距
Science	Science 系列期刊近似格式：1 英寸边距、11pt Times New Roman
IEEE Transactions（单栏近似）	IEEE Transactions 单栏近似格式：较窄边距、10pt Times New Roman
APA Manuscript	APA 第 7 版手稿近似格式：双倍行距、12pt Times New Roman

提示：期刊 / 预印本模板目前以 JSON 文件形式提供。在线工具已内置，可直接选用；桌面版用户可下载 public/tools/md2docx/templates/*.json（如 arxiv.json、nature.json 等），通过 --template-file 参数使用。

自定义模板

自定义模板为扁平 JSON，键名与工具内部读取的字段保持一致。常用字段如下：

{
  "name": "我的模板",
  "description": "自定义格式示例",
  "width_mm": 210,
  "height_mm": 297,
  "margin_top_mm": 25.4,
  "margin_bottom_mm": 25.4,
  "margin_left_mm": 25.4,
  "margin_right_mm": 25.4,
  "chinese": "宋体",
  "english": "Times New Roman",
  "heading_chinese": "黑体",
  "heading_english": "Arial",
  "code": "Consolas",
  "h1_size_pt": 16,
  "h2_size_pt": 14,
  "h3_size_pt": 12,
  "h4_size_pt": 12,
  "size_pt": 12,
  "line_spacing": 1.5,
  "first_line_indent_chars": 2,
  "alignment": "left",
  "bold": true,
  "three_line": true,
  "figure_prefix": "图",
  "table_prefix": "表",
  "number_in_paren": true,
  "toc_enabled": true,
  "footer_page_number": true
}

提示：使用 export-template 命令导出预设模板作为自定义模板的基础，再根据需要进行修改。

❓ 常见问题

公式显示为乱码？

确保文档中使用的是 Cambria Math 字体。该字体在 Windows 和 macOS 上默认安装。

中文字体显示不正确？

模板默认使用 SimSun（宋体）和 SimHei（黑体）。如果系统没有这些字体，可以在自定义模板中指定其他中文字体，如 "chinese": "Source Han Serif CN"。

图片无法加载？

支持相对路径和 HTTP/HTTPS URL。对于本地图片，请使用 --image-dir 指定图片所在目录。

如何添加页眉页脚？

在自定义模板中设置 header_text 和 footer_page_number 字段。

期刊模板是官方模板吗？

不是。arXiv、Nature、Science、IEEE、APA 等模板仅依据公开排版惯例制作的近似格式，用于初稿整理与内部审阅。正式投稿前，请务必下载并对照各平台 / 期刊的官方 LaTeX 或 Word 模板进行微调。