DOCX to Obsidian Markdown Converter

Convert Word (.docx) documents to Obsidian-compatible Markdown format, with full support for LaTeX math, tables, images, and heading structures.

When to Use This Skill

Activate this skill when:

• The user asks to convert a .docx file to .md (Markdown)
• The user mentions Obsidian Markdown format
• The user needs math formulas converted from Word equation editor (OMML) to LaTeX
• The user wants Greek letters (like λ, α, β) rendered as $\lambda$, $\alpha$, $\beta$ etc.
• The user needs to preserve academic paper formatting (headings, tables, figures, citations)

Conversion Workflow

Step 1: Parse the DOCX File

Run the conversion script:

python3 scripts/convert.py <input.docx> <output.md>

This script handles the complete conversion pipeline:

1. Document structure analysis — Identifies headings, body text, lists, tables, images, and math blocks
2. Math formula conversion — Converts Word OMML equations to LaTeX syntax
3. Image extraction — Extracts embedded images to an assets/ folder alongside the output
4. Table conversion — Converts Word tables to Markdown pipe tables
5. Output generation — Writes the final .md file in Obsidian-compatible format

Step 2: Verify the Output

After conversion, review the output for:

• Math formulas render correctly in Obsidian preview mode
• Heading hierarchy is preserved (H1/H2/H3 mapped from Word Heading styles)
• Tables display correctly
• Images are referenced with relative paths
• Greek letters and special symbols use LaTeX notation

Step 3: Manual Adjustments (If Needed)

The automated conversion covers most cases, but some edge cases may require manual review. See references/edge-cases.md for known limitations and fixes.

Math Formula Rules (CRITICAL)

This is the most important part of the conversion. Obsidian uses MathJax to render LaTeX:

Inline Math

Wrap inline math expressions with single $:

• Word OMML equation within a paragraph → $...$
• Greek letters standing alone → $\lambda$, $\alpha$, $\theta$
• Variables or short expressions → $x_i$, $f(x)$, $n \times m$

Display (Block) Math

Wrap display/block equations with double $$ on separate lines:

$$
e_{ij} = h_\theta(x_i, x_j - x_i)
$$

Greek Letter Mapping

Common Greek letters must use LaTeX commands:

Common Math Patterns

Fractions: \frac{a}{b} → $\frac{a}{b}$

Subscripts/Superscripts: x_i^2 → $x_i^2$

Summation: \sum_{i=1}^{n} → $\sum_{i=1}^{n}$

Integrals: \int_{0}^{\infty} → $\int_{0}^{\infty}$

Matrices: Use \begin{pmatrix}...\end{pmatrix} within $$ blocks

Equation numbering: Append \tag{n} within $$ blocks, e.g. $$e = mc^2 \tag{1.1}$$

Heading Mapping

Map Word heading styles to Markdown heading levels:

Table Conversion

Convert Word tables to Markdown pipe tables:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |

For merged cells or complex layouts, fall back to HTML tables:

<table>
  <tr><th>Header</th></tr>
  <tr><td>Data</td></tr>
</table>

Image Handling

1. Extract all embedded images from the .docx to an assets/ folder next to the output .md file
2. Use relative paths in Markdown: ![description](assets/image-001.png)
3. Preserve captions as alt text or adjacent paragraphs

Citation Handling

Word cross-references and citations (e.g., [5], [6]) should be preserved as-is in the Markdown text. If the user wants to convert to Obsidian's citation format later, that is a separate step.

File References

• If you encounter complex OMML math that the script cannot auto-convert, read references/omml-to-latex.md for the full mapping table
• If you encounter edge cases in table conversion, read references/edge-cases.md
• If you need to extract images with specific naming conventions, read references/image-extraction.md