Use DOCX page output for citations

Read Markdown by page, separate headers and footers, and preserve document version information for citations and RAG ingestion.

Use result.pages when your application needs to associate extracted text with a page. The converter calculates pages with the DOCX Editor layout engine and returns Markdown for each page's body, header, and footer.

Read page output

import { readFile } from 'node:fs/promises';
import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';

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

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

page.number is a one-based physical page number for this export. It is not necessarily the printed page label in a Word field. result.markdown contains the joined document body and excludes repeated headers and footers.

Store a document version with citations

Page numbers and IDs apply to one export. Fonts, document edits, and revision mode can change page breaks. Store a document version or content hash alongside each page citation:

import { createHash } from 'node:crypto';

const documentVersion = createHash('sha256').update(bytes).digest('hex');

const records = result.pages.map((page) => ({
  text: page.markdown,
  metadata: {
    documentVersion,
    pageNumber: page.number,
    pageId: page.id,
    pagination: result.pagination,
  },
}));

Also record your converter version and font configuration if you need to reproduce an export. Avoid using a page number alone as a durable document reference.

Prepare content for RAG

For proposed document text, set displayMode: 'proposed':

const result = await exportMarkdown(bytes, {
  displayMode: 'proposed',
});

This includes pending insertions and hides pending deletions. It does not accept the changes in the source file.

Map each page to your ingestion system's document type. If you split a page into smaller chunks, retain the page metadata on each chunk. If a chunk joins text from several pages, record every contributing page instead of assigning only the first.

See the LangChain integration example for creating a document for each page.

Keep review metadata

Comments and tracked changes are available separately from Markdown:

for (const page of result.pages) {
  console.log(page.comments);
  console.log(page.trackedChanges);
}

console.log(result.reviewArtifacts);
console.log(result.reviewBindings);

Page arrays contain artifacts with occurrences on that page. One artifact can span multiple pages. result.reviewArtifacts also includes artifacts without a page occurrence.

reviewBindings associates artifacts with offsets in the generated Markdown. The offsets use JavaScript UTF-16 string indexing and apply only to that export. See the review binding reference before using them for citations or edits.

Understand pagination limits

The layout engine resolves fonts, images, and document geometry before generating page output. Its page breaks can differ from Microsoft Word.

For reproducible pagination, pin library versions, supply the fonts your documents use, and retain result.fontResolution. Font substitution and unsupported document features can change layout. Review result.warnings for omitted content and incomplete fonts.

Use fontPolicy: 'strict' when you need the exporter to reject missing required font faces or font-source failures. Strict success applies to the engine's candidate font list, which is bounded; it is not a guarantee that every font in an arbitrarily large document was checked.