Convert Word to Markdown with page references

Layout-aware, paged Markdown conversion for document agents and RAG.

DOCX to Markdown API guidedocx-to-markdown.com
Open full-screen demo (opens in a new tab)

Use it in your application

Available as TypeScript and Python packages.

View on npm

Add the converter to your TypeScript or JavaScript application. Includes the required core dependency.

Extract text with page context

Convert Word (.docx) files to paginated Markdown for agents and retrieval-augmented generation (RAG). Keep page references with body text and read headers and footers separately.

Pages from document layout

The layout engine calculates page boundaries. Retrieve Markdown by page, or use the continuous document body.
Read the guide

Separate headers and footers

Read each page's header and footer separately. Index the body without repeating document labels in every chunk.
Read the guide

Structured content and review data

Extract headings, lists, tables, comments, and tracked changes. Enable image extraction when needed. Check warnings for omitted content.
Read the guide

Why do page references need a layout engine?

Page boundaries depend on fonts and document layout. Saved page-break hints can be missing or stale. The converter calculates layout before exporting Markdown.

Build RAG with page references

Attach source metadata before splitting text into retrieval chunks. Pass the retrieved text and its page references to your model.

  1. 01

    Convert a document snapshot

    Convert DOCX bytes with the library. Set fonts and revision visibility; both affect page boundaries.

    Configure fonts
  2. 02

    Store the source with each page

    Store the document ID, version, export ID, and page number with each chunk.

    Build page citations
  3. 03

    Let readers inspect the source

    Include the document version and page reference in each answer. Retain the export so readers can check the source.

    Add a document viewer

Convert DOCX to .md in TypeScript

Save the document as Markdown or read each page separately. Use page numbers to keep source references with retrieved text.

Check conversion warnings. Page breaks can differ from Word.

Read the integration guide
convert.mtsNode.js / TypeScript
import { readFile, writeFile } from 'node:fs/promises';
import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';

const bytes = await readFile('document.docx');
const result = await exportMarkdown(bytes);

await writeFile('document.md', result.markdown, 'utf8');

for (const page of result.pages) {
  console.log(page.number, page.markdown);
}

console.log(result.warnings);

Add paginated Markdown to your ingestion pipeline

LangChain

Create documents from each page

Map page Markdown to LangChain documents. Keep source and page metadata when splitting text into retrieval chunks.

Docling pipelines

Add a DOCX conversion step

Use this converter for DOCX alongside Docling for other formats. Map the page output to your pipeline's text and metadata fields.

Elasticsearch and vector stores

Index text with page references

Embed the text and store it in Elasticsearch or another vector store. Keep the document version and page number with each chunk for citations.

Common questions

How do I save DOCX output as a .md file in Node.js?

Write the continuous Markdown output to a UTF-8 .md file. The Node.js example on this page saves document.md. Store page records separately for citations; a .md file does not retain page metadata.

Can I convert a legacy .doc file to Markdown?

No. Save it as .docx first. The converter accepts .docx input only.

Will the page numbers match Microsoft Word?

Not always. Fonts, document features, and revision visibility can change page breaks. Configure fonts and check representative files against Word. Page numbers identify physical pages starting at 1, not printed labels that restart by section.

Does Markdown preserve the Word page design?

Markdown preserves supported content and structure, not the full page design. The converter uses layout to group content by page. Continuous Markdown joins split content and omits repeated headers and footers.

Do I need Pro to export pages or review data?

No. Conversion, page output, and review extraction use Apache 2.0. Interactive review editing requires Pro. Bundled fonts retain their own licenses.

Can I run conversion in a serverless function?

Yes. Use a supported Node.js runtime and bundle the WebAssembly and font assets. Allocate CPU and memory for layout. Next.js Edge is unsupported.

Why is DOCX pagination difficult for retrieval tools?

Text extraction alone cannot determine page numbers. Fonts, spacing, and tables affect pagination. A layout engine calculates which text belongs to each page.

For background, see the MarkItDown page-number request, Docling explanation of DOCX page information, and LangChain report of incorrect page metadata.

Convert your first document

Try the converter on docx-to-markdown.com or add the TypeScript or Python package to your application.

Open docx-to-markdown.comIntegrate the library

Need to review and edit the source? Explore DOCX agents or read about Pro review editing.