microsoft / microsoft/markitdown

Add support for mathematical formulas in DOCX conversion

Open
#289 3 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
186k
Forks
13.7k
Avg merge
1d 4h
Merged PRs (30d)
49

Description

Issue Description
When converting DOCX files containing mathematical formulas to Markdown, the formulas are currently not properly converted. This limits the utility of MarkItDown for academic and technical documents where mathematical expressions are common.

Current Behavior

  • Mathematical formulas in DOCX files are either skipped or converted incorrectly
  • No support for converting Office Math ML (OMML) to LaTeX or other markdown-compatible formats

Expected Behavior

  • Mathematical formulas should be converted to LaTeX format, which is widely supported in Markdown renderers
  • The conversion should preserve the mathematical meaning and formatting of the original formulas
  • Support for both inline and display math modes

Use Cases

  1. Converting academic papers with mathematical content
  2. Processing technical documentation containing equations
  3. Converting educational materials with mathematical expressions

Suggested Implementation

  1. Add support for parsing Office Math ML (OMML) from DOCX files
  2. Implement conversion from OMML to LaTeX
  3. Properly handle both inline and display math modes in the output markdown
  4. Consider using existing libraries like omml2mathml for initial conversion to MathML, then convert to LaTeX

Additional Context
This feature would significantly enhance MarkItDown's utility for academic and technical users who frequently work with mathematical content.

Environment

  • MarkItDown version: [latest]
  • Python version: 3.x
  • OS: All platforms

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing DOCX-to-Markdown conversion path and its tests, then inspect how Office Math ML is represented in DOCX files. Evaluate the suggested OMML-to-MathML route and LaTeX output requirements. Done means preserving mathematical meaning in both inline and display formulas with coverage for the stated academic and technical use cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
content
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.