Convert Word (DOCX) to Markdown

POST /v1/convert converts a Word file (.docx) to Markdown in one call. Headings, lists and tables come from the document's own styles, and equations become LaTeX.

curl

Set the content type. curl sends a .docx file as application/octet-stream, which the API rejects with 415.

curl -F "file=@spec.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  https://api.flatmark.dev/v1/convert

{"markdown": "# Specification\n\n## Scope\n\nThis document covers the export format.\n\n* First item\n* Second item\n\n...", "meta": {"filename": "spec.docx"}}

Python: convert a folder

import pathlib

import httpx

DOCX = "application/vnd.openxmlformats-officedocument.wordprocessingml.document"


def docx_to_markdown(path: pathlib.Path) -> str:
    with path.open("rb") as fh:
        resp = httpx.post(
            "https://api.flatmark.dev/v1/convert",
            files={"file": (path.name, fh, DOCX)},
            headers={"X-API-Key": "YOUR_KEY"},  # optional
            timeout=60,
        )
    resp.raise_for_status()
    return resp.json()["markdown"]


for doc in sorted(pathlib.Path("specs").glob("*.docx")):
    target = doc.with_suffix(".md")
    target.write_text(docx_to_markdown(doc), encoding="utf-8")
    print(doc.name, "->", target.name)

What carries over

• Headings: paragraphs styled as Heading 1, Heading 2 and so on become #, ## and so on.
• Lists and tables become Markdown lists and pipe tables. A table without a marked header row gets an empty header row.
• Equations, also in footnotes and endnotes, become LaTeX: $...$ inline and $$...$$ as a block.
• Images are not extracted. The output is text.

Next step

Convert a .docx file in the browser, up to 4 MB and without an account.

FAQ

Can I convert a .doc file?

No. Only .docx is accepted, and .doc is rejected with an error (415). Word, LibreOffice and Google Docs can save a file as .docx.

Does the JSON output show page numbers for Word files?

No. A Word file has no fixed pages, so the queue's JSON structure file carries no page numbers for it. PDF, PowerPoint and Excel files have them.