Markdown to DOCX / Markdown to Word documentation

This page explains how the md2docx service converts Markdown to DOCX and Markdown to Word, and how you can get the most out of the converter when working with technical content, AI generated drafts, and team documentation.

Why convert Markdown to DOCX or Word

Many engineers and writers prefer Markdown because it keeps content close to plain text and plays well with version control and tools like ChatGPT or other language models. Stakeholders, however, usually expect Word documents or DOCX files that they can review, comment on, and route through approvals. md2docx exists to bridge this gap by letting you convert Markdown to DOCX online without installing desktop plugins or rewriting content by hand.

A common workflow is to draft a proposal or architecture document in Markdown, often inside a code repository or copied from a ChatGPT conversation. When the text is ready, you paste the Markdown into the converter, choose a template, and download a consistent Word document that matches the rest of your organization's reports. This keeps authors productive in Markdown while still delivering polished documents to business stakeholders.

Supported Markdown features

1. Core Markdown

• Headings: # through ###### map to Word heading levels 1–6.
• Paragraphs and hard line breaks.
• Emphasis: *italic* / _italic_, **bold**, __bold__.
• Inline code: `code`, rendered with a monospace font.
• Blockquotes: > quoted text, styled with a left border.
• Horizontal rules: --- by default, or page/section breaks when options are enabled.
• Links: [text](https://example.com) are preserved as clickable hyperlinks in the DOCX output.

2. Lists

We support both bullet and ordered lists, including nesting.

- Bullet item 1
- Bullet item 2

1. Numbered item 1
2. Numbered item 2

In the DOCX file, these become proper Word lists, with bullet and numbering styles. Nested lists are supported and mapped to deeper list levels.

3. Tables

GitHub-style tables are supported via markdown-it-multimd-table and are preserved when you convert Markdown to DOCX online:

| Column A | Column B |
|----------|----------|
| Row 1    | Value 1  |
| Row 2    | Value 2  |

These are rendered as real Word tables with columns sized to fit the page width, so the Word version is easy to read and edit.

4. Images

Remote images referenced in Markdown are embedded into the DOCX when the “Embed images from remote URLs” option is enabled:

![Alt text](https://example.com/image.png)

• Only HTTP(S) URLs are supported; local file paths from Markdown are ignored.
• Images are scaled to fit within a safe width/height for Word documents.

5. Diagrams (Mermaid, Graphviz, PlantUML)

We support several diagram syntaxes rendered to PNG and embedded into the DOCX, which is useful when you want architecture or flow diagrams to travel with the Word document:

• Mermaid

  ```mermaid
  graph TD;
    A-->B;
    B-->C;
  ```

• Graphviz / DOT

  ```graphviz
  digraph G {
    A -> B;
    B -> C;
  }
  ```

• PlantUML

  ```plantuml
  Alice -> Bob: Hello
  ```

For Graphviz and PlantUML, the corresponding CLI tools must be available on the server. If rendering fails, the fenced block is included as a formatted code block instead.

6. Charts (Chart.js)

You can embed Chart.js charts by including a JSON Chart.js configuration inside a ```chartjs fenced block. The converter turns that configuration into a chart image inside the DOCX:

```chartjs
{
  "type": "bar",
  "data": {
    "labels": ["Q1", "Q2", "Q3", "Q4"],
    "datasets": [
      { "label": "2024", "data": [10, 15, 8, 20] }
    ]
  }
}
```

The configuration is rendered server-side with Chart.js into a PNG and embedded. If the JSON is invalid or rendering fails, the JSON is rendered as a code block for debugging.

7. Math (TeX)

md2docx supports TeX-style math via markdown-it-katex and MathJax:

• Inline math: $E = mc^2$
• Block math: $$ E = mc^2 $$

Block math and inline math are rendered via MathJax to SVG and then rasterized to PNG images, which are embedded into the DOCX so the visual formatting matches your TeX.

8. Admonitions / callouts

We support container-style admonitions via markdown-it-container:

:::note
This is an informational note.
:::

:::warning
This is a warning block.
:::

:::tip
Helpful tips can go here.
:::

These are rendered as styled callout blocks in the DOCX. When the “Prefix callouts with labels” option is enabled, the first line in each block is prefixed with “Note:”, “Warning:”, or “Tip:” in bold.

9. Templates, TOC, and layout options

• Per-request template upload: upload a DOCX template to control fonts, spacing, and styles.
• Sample templates: choose from built in templates when you do not have your own.
• Table of contents: enable the TOC option to insert a Word TOC based on headings 1–3.
• Page/section breaks:
  • --- can become a page break and/or section break.
  • Top-level headings (# Heading) can start on new pages.

10. Limitations & tips

• Raw HTML in Markdown is disabled for security reasons.
• Remote image fetching is limited to HTTP(S) and size-capped for performance.
• If something doesn’t render as expected, try including the raw Markdown in a bug report via the Contact page.