MathFmt

中文 | English

MathFmt turns plain-text formulas in Word documents into native Word OMML equations — stacked fractions, radicals, superscripts, subscripts, derivatives, and standard mathematical operators — suitable for textbooks, exams, and technical reports.

Quick Start · 快速开始

Who is this for? Anyone who writes math-heavy Word documents — teachers preparing exams, students writing lab reports, engineers drafting technical specs. If you type formulas like x^2 or sqrt(a/b) in Word and want them rendered as proper equations, MathFmt is for you.

适合谁用？ 需要在 Word 里写数学公式的人——老师出试卷、学生写实验报告、工程师写技术文档。如果你在 Word 里输入 x^2 或 sqrt(a/b) 这样的文本公式，想让它们变成原生公式，MathFmt 就是你的工具。

Install · 安装

pip install mathfmt

Requirements: Python ≥ 3.10. The only runtime dependency is lxml.

Check your environment · 检查环境

mathfmt doctor

Prints MathFmt, Python, lxml/libxml2/libxslt versions, backend availability, and platform info — useful before filing a bug report.

Convert a document · 转换文档

# One-step conservative conversion (high-confidence formulas only)
mathfmt convert input.docx --output output.docx

# Scan first, review candidates, then apply (recommended for production)
mathfmt scan input.docx --report candidates.json
mathfmt apply input.docx --review candidates.json --report preview.json --dry-run
mathfmt apply input.docx --review candidates.json --output output.docx --report result.json
mathfmt apply input.docx --review candidates.json --output output.docx --report result.json --strict

For detailed workflow, see docs/workflow.md.

You can mark formulas explicitly in DOCX text with $...$ for inline equations or $$...$$ for display equations. MathFmt removes the delimiters when it inserts the native Word equation.

Reviewed formulas can span multiple aligned lines. Put \\ or a real line break in the candidate's linear value, for example a = b \\ c = d; MathFmt creates one native Word equation array and aligns the rows at their first relation symbol.

Piecewise formulas support both f(x) = {0, x<0; 1, x>=0} and cases(0 if x<0; 1 if x>=0). Both render as a native Word expression with a left brace and aligned expression/condition columns.

Basic chemistry notation is also supported: H2O, CO2, and NaCl use upright element symbols and native subscripts; reactions such as 2H2 + O2 -> 2H2O support ->, <->, and =>, plus (aq)/(g)/(l)/(s) states and ->[heat] annotations.

Physics notation includes stacked partial derivatives (partial f / partial x or ∂f/∂x), tensor indices such as T_i^j, and bra-ket forms including <phi|psi>, ⟨φ|ψ⟩, and bra(phi) ket(psi).

Custom symbol aliases can be supplied with --aliases. A minimal JSON profile is:

{
  "name": "engineering",
  "aliases": {
    "ohm": "Ω",
    "mapsTo": "↦"
  }
}

Pass the same profile to each review-first command:

mathfmt scan input.docx --report candidates.json --aliases symbols.json
mathfmt apply input.docx --review candidates.json --output output.docx --report result.json --aliases symbols.json

Alias tokens may add one Unicode mathematical symbol but cannot replace MathFmt keywords such as sqrt, lim, sum, or partial. Reports record the profile name, absolute path, symbol count, and SHA-256 digest.

Status

Beta (v0.5.0). Cross-platform OMML, structured safety reports, batch conversion, WPS compatibility checks, explicit LaTeX delimiters, aligned and piecewise equations, chemistry and physics notation, and custom symbol aliases.

中文

MathFmt 将 DOCX 中的普通文本公式排版为 Word 原生 OMML 公式。

快速示例

兼容性

¹ 需手动指定 MML2OMML.XSL 路径（--xsl）。
² macOS 版 Microsoft Word。 ³ 已使用 WPS Writer 12.0 完成隐藏打开、DOCX 往返保存和 PDF 视觉验收。 ⁴ --compatibility wps 离线检查可在 Linux 运行；Linux 版 WPS 的原生视觉验收仍需手工执行。

命令

mathfmt scan    input.docx --report candidates.json   # 扫描公式候选
mathfmt apply   input.docx --review candidates.json --report preview.json --dry-run  # 仅预览，不写 DOCX
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json  # 审核后转换
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json --strict  # 失败则不写输出
mathfmt convert input.docx                           # 保守一键转换
mathfmt convert "folder/*.docx" --output-dir converted --batch-report batch.json  # 批量转换
mathfmt validate input.docx                           # 离线结构验证
mathfmt validate input.docx --compatibility wps       # WPS 兼容性检查
mathfmt doctor                                        # 环境诊断
mathfmt update                                        # 检查 GitHub 更新

更新

mathfmt update              # 检查更新并显示安装命令
mathfmt update --check      # CI 模式：有更新时退出码 1，最新时退出码 0
mathfmt update --pre        # 包含预发布版本
mathfmt update --force      # 跳过缓存，立即检查 GitHub

检测结果缓存 1 小时。也可直接运行：

pip install --upgrade mathfmt

版本路线

更多文档

• 公式语法参考 — 完整预处理规则、语法、MathML 映射和限制
• 工作流指南 — 安装、审核流程、错误处理、CI 使用
• 示例 — 从零开始的测试文档准备和转换教程
• 路线图 — 版本规划与功能展望

维护

单人维护（Leo），尽力响应。欢迎提交 Issue 和 PR，也可通过 gml853503962@gmail.com 联系。安全漏洞请参阅 SECURITY.md。

English

MathFmt converts plain-text formulas in DOCX files into native Word OMML equations.

Quick Examples

Compatibility

¹ Manual --xsl path required for Office XSL backend.
² Microsoft Word for Mac. ³ Round-trip DOCX save and PDF visual QA completed with WPS Writer 12.0. ⁴ The offline --compatibility wps profile runs on Linux; native Linux WPS visual QA remains manual.

Commands

mathfmt scan    input.docx --report candidates.json   # Scan formula candidates
mathfmt apply   input.docx --review candidates.json --report preview.json --dry-run  # Preview only
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json  # Apply reviewed candidates
mathfmt apply   input.docx --review candidates.json --output out.docx --report result.json --strict  # Do not write output on failures
mathfmt convert input.docx                           # Conservative one-step conversion
mathfmt convert "folder/*.docx" --output-dir converted --batch-report batch.json  # Batch conversion
mathfmt validate input.docx                           # Offline structure validation
mathfmt validate input.docx --compatibility wps       # WPS compatibility lint
mathfmt doctor                                        # Environment check
mathfmt update                                        # Check GitHub for updates

Updating

mathfmt update              # Check for updates and show install commands
mathfmt update --check      # CI mode: exit 1 when update available, 0 when current
mathfmt update --pre        # Include pre-release versions
mathfmt update --force      # Skip cache, re-check GitHub immediately

Check results are cached for 1 hour. You can also upgrade directly:

pip install --upgrade mathfmt

Version Roadmap

Further Reading

• Formula Syntax Reference — every preprocessing rule, the full grammar, MathML output mapping, and known limitations
• Workflow Guide — step-by-step install, review flow, troubleshooting, CI usage
• Examples — walkthrough from a blank test document to formatted output
• Roadmap — planned features and version timeline

Maintenance

Single-maintainer project (Leo), best-effort response. Issues and pull requests are welcome. You can also contact the maintainer at gml853503962@gmail.com. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

Contributing

Issues and pull requests are welcome.

License

MIT License. Copyright (c) 2026 Leo.