@docx-editor.dev/docx-to-markdown

createMarkdownZipfunctionSource ↗

Create a portable ZIP containing document.md, document.json, and media files.

declare function createMarkdownZip(result: MarkdownExportResult): Promise<Uint8Array>;

exportMarkdownfunctionSource ↗

Convert untrusted DOCX bytes with Node-safe resource and shaping defaults.

declare function exportMarkdown(source: ExportDocumentSource, options?: MarkdownExportOptions): Promise<MarkdownExportResult>;

exportMarkdownFromfunctionSource ↗

Translate an existing shared export session without reopening or re-laying out it.

declare function exportMarkdownFrom(session: ExportSession, options?: MarkdownProjectionOptions): Promise<MarkdownExportResult>;

exportMarkdownLayoutfunctionSource ↗

Translate a detached immutable core layout after its producer session is disposed.

declare function exportMarkdownLayout(layout: ExportSemanticLayout): MarkdownExportResult;

forEachSemanticDrawingfunction

Visit every drawing through the canonical root-story and recursive textbox walks.

declare function forEachSemanticDrawing(layout: SemanticLayout, visit: (drawing: SemanticDrawingVisit) => void): void;

openDocumentForExportfunctionSource ↗

Open a reusable export session with packaged fonts and HarfBuzz shaping by default.

declare function openDocumentForExport(source: ExportDocumentSource, options?: OpenMarkdownDocumentForExportOptions): Promise<OpenMarkdownDocumentForExportResult>;

toMarkdownJSONfunctionSource ↗

Omit image bytes and normalize arbitrary font failure causes to diagnostic strings.

declare function toMarkdownJSON(result: MarkdownExportResult): MarkdownJSONResult;

DocumentOpenErrorclassSource ↗

Typed one-shot failure for bytes that cannot be opened as a supported DOCX.

declare class DocumentOpenError extends Error

ExportResourceErrorclassSource ↗

Bounded failure from a headless export session.

declare class ExportResourceError extends Error

MarkdownBundleErrorclassSource ↗

Failure to write a complete portable Markdown bundle.

declare class MarkdownBundleError extends Error

MarkdownMediaErrorclassSource ↗

Failure to produce a complete image export.

declare class MarkdownMediaError extends Error

AnchoredDrawingRecordinterface

interface AnchoredDrawingRecord extends Omit<InlineDrawingRecord, 'kind' | 'baselineOffset' | 'advanceStart' | 'advanceEnd' | 'distL' | 'distR' | 'distT' | 'distB'>

DrawingAccessibilityinterface

interface DrawingAccessibility

DrawingGeometryinterface

interface DrawingGeometry

DrawingTransforminterface

interface DrawingTransform

ExportContentWarninginterface

Source content that cannot be certified by the layout snapshot.

interface ExportContentWarning

ExportDestinationAnchorinterface

Model address shared by bookmarks and internal hyperlinks.

interface ExportDestinationAnchor

ExportDestinationGeometryinterface

Laid-out jump target in the coordinate spaces export traversal uses.

interface ExportDestinationGeometry

ExportDroppedEmbeddedFontinterface

One document-embedded face the export mapper refused before composition.

interface ExportDroppedEmbeddedFont

ExportFontFaceResolutioninterface

One paintable face in an export font-resolution report.

interface ExportFontFaceResolution

ExportFontFamilyResolutioninterface

Coverage of one family Core layout may request.

interface ExportFontFamilyResolution

ExportFontResolutionReportinterface

Exporter-neutral evidence for the font policy behind one layout session.

interface ExportFontResolutionReport

ExportSemanticLayoutinterface

Export-ready semantic snapshot. Core guarantees normalized review artifacts for every session, including an empty immutable array when the source has none. A resolved snapshot is recursively immutable and remains traversable after its producer session is disposed; disposal only revokes session-owned work and capabilities such as [ExportSession.validatedImageBytes](ExportSession.validatedImageBytes).

interface ExportSemanticLayout extends SemanticLayout

ExportSessioninterface

A single semantic-layout substrate reusable by Markdown and later exporters. Pagination fidelity is determined by the session's measurer; core's default is deterministic, not font-accurate.

interface ExportSession

FontOriginFailureinterface

A failed font origin or a partial failure in an otherwise usable fragment.

interface FontOriginFailure

FontRequestinterface

A face, as something asks for it: family plus the two axes this engine admits.

Only static weights and slants. Variable-font axes are deliberately outside this vocabulary — the shaper refuses variation axes, and a variable file admitted here would render bold at regular weight.

interface FontRequest

FontSubstitutioninterface

A request that was answered by a DIFFERENT face than the one asked for.

Recorded rather than silently applied, because a substitution changes measurement: it is part of the shaping fingerprint, so a cached run shaped against a substitute is never reused for the real face.

interface FontSubstitution

HeadlessDocumentViewinterface

The read capabilities shared by browser layout, server export, and future renderers.

It deliberately exposes resolved package facts rather than a binding or editor session. An exporter can therefore consume the live document without importing ProseMirror or a DOM.

interface HeadlessDocumentView

ImageDecodePortinterface

The injected image decoder.

A port rather than a direct Image/createImageBitmap call, so a worker or server runtime supplies its own and the engine never reaches for a browser global.

interface ImageDecodePort

InlineDrawingRecordinterface

interface InlineDrawingRecord

LayoutBoxinterface

A rectangle in layout POINTS.

Points everywhere in this layer — twips convert at property-read boundaries and CSS pixels at paint. A box carrying either of those would eventually be added to one carrying the other.

interface LayoutBox

MarkdownExportOptionsinterfaceSource ↗

Layout and resource controls for one-shot Markdown export.

interface MarkdownExportOptions extends OpenMarkdownDocumentForExportOptions, MarkdownProjectionOptions

MarkdownExportResultinterfaceSource ↗

Full logical document plus page-scoped projections.

interface MarkdownExportResult

MarkdownExportSessioninterfaceSource ↗

Reusable Markdown session with the font evidence captured while it opened.

interface MarkdownExportSession extends ExportSession

MarkdownImageAssetinterfaceSource ↗

One unique image returned by a Markdown export.

interface MarkdownImageAsset extends MarkdownImageData

MarkdownImageDatainterfaceSource ↗

Image bytes and provenance supplied to a URL resolver.

interface MarkdownImageData

MarkdownImageOccurrenceinterfaceSource ↗

One physical occurrence of an extracted image.

interface MarkdownImageOccurrence

MarkdownImageOptionsinterfaceSource ↗

Portable image extraction and optional application-owned storage.

interface MarkdownImageOptions

MarkdownPageinterfaceSource ↗

Markdown emitted for one physical layout page.

interface MarkdownPage

MarkdownPaginationInfointerfaceSource ↗

Machine-readable scope of the page numbers returned by this export.

interface MarkdownPaginationInfo

MarkdownProjectionOptionsinterfaceSource ↗

Projection controls for an already-open export session.

interface MarkdownProjectionOptions

MarkdownReviewBindinginterfaceSource ↗

Honest snapshot-local mapping from a Core review occurrence to generated Markdown.

interface MarkdownReviewBinding

MarkdownReviewRangeinterfaceSource ↗

A UTF-16 range suitable for slicing the named Markdown projection.

interface MarkdownReviewRange

MarkdownWarninginterfaceSource ↗

Content or resources that could not be represented fully.

interface MarkdownWarning

OpenDocumentForExportOptionsinterface

Shared session options; translators add their own format-specific options.

interface OpenDocumentForExportOptions

OpenMarkdownDocumentForExportOptionsinterfaceSource ↗

Layout controls for a reusable Markdown export session.

interface OpenMarkdownDocumentForExportOptions extends OpenDocumentForExportOptions

RevisionAttributioninterface

One revision wrapper's provenance, as authored.

id is the verbatim @w:id string rather than a number: ST_DecimalNumber restricts xsd:integer with no bounds, so a file may carry a value outside the safe integer range, and parsing it to a number would silently merge two distinct revisions.

date is absent when the file omits it. @w:date is optional on CT_TrackChange, and inventing one is a silent content change.

interface RevisionAttribution

SemanticCommentArtifactRecordinterface

Normalized comment; all relation ids share the opaque snapshot-local id space.

interface SemanticCommentArtifactRecord

SemanticDrawingVisitinterface

One drawing in bounded graph-enumeration order with exporter-grade provenance.

Enumeration is deliberately not paint order: story anchors (and nested textboxes) are visited before inline line drawings. Renderers use paintLayer plus record geometry to compose layers.

interface SemanticDrawingVisit extends StoryDrawingContext

SemanticLayoutinterface

A complete layout pass: every page, plus the document-wide indexes derived alongside them.

Stamped with the store revision it was laid out from, so anything holding geometry can tell whether the document has moved underneath it — which is how stale pointer gestures and overlays are refused rather than applied to coordinates that no longer describe anything.

interface SemanticLayout

SemanticReviewArtifactOccurrenceinterface

One physical occurrence of a comment or tracked-change source range.

interface SemanticReviewArtifactOccurrence

SemanticReviewArtifactOccurrenceGeometryinterface

Laid-out bounds for one review occurrence.

pageContent uses the same space as line boxes. pageStack uses stacked page coordinates. A point occurrence publishes width: 0.

interface SemanticReviewArtifactOccurrenceGeometry

SemanticReviewArtifactPositioninterface

One model position retained as exporter provenance.

interface SemanticReviewArtifactPosition

SemanticReviewArtifactSourceinterface

Package-relative snapshot provenance, not durable public identity.

Engine-produced occurrences keep start.paragraphId === end.paragraphId. Cross-paragraph source ranges are sliced into per-paragraph occurrences before geometry attaches.

interface SemanticReviewArtifactSource

SemanticTrackedChangeArtifactRecordinterface

Normalized change; ids are opaque and stable only within the source snapshot.

interface SemanticTrackedChangeArtifactRecord

SourceCropinterface

a:srcRect — how much of each edge of the source image is cropped away, as fractions.

interface SourceCrop

TextboxStoryLayoutinterface

One text box's story laid out inside its extent, in content-box-relative coordinates.

Fragments origin at the content box's top-left; paint places the content box at drawing origin + contentOffset and clips to the extent.

interface TextboxStoryLayout

TextMeasurerinterface

Text measurement, injected.

A real implementation shapes with the resolved font; the tests supply a deterministic one. Layout never reads the DOM, so this is the only way width and height enter it.

interface TextMeasurer

VectorShapeProjectioninterface

The renderable subset of a wps:wsp non-picture graphic, or of one bounded wpg:wgp group of them: closed polygon subpaths (a:custGeom with move/line/close/cubicBezTo verbs, or a supported a:prstGeom) with a solid fill and/or stroke. The colour may come from a:srgbClr or from the theme, through a:schemeClr or a wps:style matrix reference. Anything richer (gradient and picture fills, text bodies, rotation, a nested group) projects as null and paints the labelled placeholder instead.

interface VectorShapeProjection

AnchoredDrawingLayoutFallbacktype

Named fallback when a positioning frame cannot be resolved (OpenSpec 4.6).

type AnchoredDrawingLayoutFallback = 'unresolvable-frame' | 'page-defer-exhausted';

DrawingHorizontalReferenceFrametype

type DrawingHorizontalReferenceFrame = 'character' | 'column' | 'insideMargin' | 'leftMargin' | 'margin' | 'outsideMargin' | 'page' | 'rightMargin';

DrawingVerticalReferenceFrametype

type DrawingVerticalReferenceFrame = 'bottomMargin' | 'insideMargin' | 'line' | 'margin' | 'outsideMargin' | 'page' | 'paragraph' | 'topMargin';

ExportDocumentMetadatatype

Bounded package metadata for exporter output dictionaries.

type ExportDocumentMetadata = Readonly<DocumentProperties>;

ExportDocumentSourcetype

Source accepted by every exporter: untrusted bytes or an already-open live view.

type ExportDocumentSource = Uint8Array | HeadlessDocumentView;

HeadlessDocumentRejectiontype

A bad package is data, not an exceptional control path.

type HeadlessDocumentRejection = OoxmlPackageRejection | 'no-main-document-tree';

ImageResourceStatetype

What is known about one embedded image: validated, refused, or still decoding.

Content type is a CLAIM. Signature sniffing, structural header validation and the decode port are authoritative, and bytes that fail them never enter public state.

type ImageResourceState = {
    readonly kind: 'ready';
    readonly partName: string;
    readonly contentId: string;
    readonly resourceKey: string;
    readonly validatedHandle: ValidatedImageBytesHandle;
    readonly mime: RenderableImageMime;
    readonly pixelWidth: number;
    readonly pixelHeight: number;
    readonly dpiX: number;
    readonly dpiY: number;
} | {
    readonly kind: 'unrenderable';
    readonly partName: string | null;
    readonly mime: RenderableImageMime | PreservedImageMime | 'unknown';
    readonly reason: 'unsupported-format' | 'non-picture-graphic' | 'signature-mismatch' | 'decode-failed' | 'resource-limit';
} | {
    readonly kind: 'external';
    readonly relationshipId: string;
    readonly sinkSafe: boolean;
} | {
    readonly kind: 'missing';
    readonly relationshipId: string;
} | {
    readonly kind: 'pending';
    readonly resourceKey: string;
};

ImageWrapTargettype

Nine Word wrap menu targets (inline plus eight floating modes).

type ImageWrapTarget = 'inline' | 'square' | 'squareLeft' | 'squareRight' | 'tight' | 'through' | 'topAndBottom' | 'behind' | 'inFront';

MarkdownCommenttypeSource ↗

Normalized DOCX comment, independent of editor UI state.

Its ID is opaque and stable only within one [MarkdownExportResult](MarkdownExportResult). Never persist the ID across exports; pair citations with the caller's own document version or content hash.

type MarkdownComment = SemanticCommentArtifactRecord;

MarkdownFontOrigintypeSource ↗

One caller-controlled font origin used for headless pagination.

type MarkdownFontOrigin = FontOrigin;

MarkdownFontsSourcetypeSource ↗

One font origin, or an ordered first-wins list of origins.

type MarkdownFontsSource = MarkdownFontOrigin | readonly MarkdownFontOrigin[];

MarkdownJSONImagetypeSource ↗

JSON-safe image metadata. Binary bytes are delivered separately.

type MarkdownJSONImage = Omit<MarkdownImageAsset, 'bytes'>;

MarkdownJSONResulttypeSource ↗

JSON-safe export for HTTP responses and portable bundle manifests.

type MarkdownJSONResult = Omit<MarkdownExportResult, 'media' | 'fontResolution'> & {
    readonly media: readonly MarkdownJSONImage[];
    readonly fontResolution: (Omit<NonNullable<MarkdownExportResult['fontResolution']>, 'originFailures'> & {
        readonly originFailures: readonly {
            readonly originIndex: number;
            readonly originName?: string;
            readonly cause: string;
        }[];
    }) | null;
};

MarkdownReviewArtifacttypeSource ↗

Comment or tracked change returned by Markdown export. IDs are opaque and result-local.

type MarkdownReviewArtifact = SemanticReviewArtifactRecord;

MarkdownReviewCoveragetypeSource ↗

How much of one Core source occurrence is represented by the returned ranges.

type MarkdownReviewCoverage = 'complete' | 'partial' | 'none';

MarkdownReviewOccurrencetypeSource ↗

Page/story/source provenance for one exported review artifact.

type MarkdownReviewOccurrence = SemanticReviewArtifactRecord['occurrences'][number];

MarkdownReviewProjectiontypeSource ↗

Markdown string containing one review binding.

type MarkdownReviewProjection = {
    readonly kind: 'document';
} | {
    readonly kind: 'page';
    readonly pageIndex: number;
    readonly pageNumber: number;
    readonly field: 'markdown' | 'headerMarkdown' | 'footerMarkdown';
};

MarkdownReviewRangePrecisiontypeSource ↗

Precision of a source-to-Markdown review range.

type MarkdownReviewRangePrecision = 'exact' | 'containing-construct';

MarkdownReviewUnmappedReasontypeSource ↗

Why a source occurrence has no range in a particular Markdown projection.

type MarkdownReviewUnmappedReason = 'not-represented-in-markdown' | 'non-linear-structural-change' | 'omitted-story-content';

MarkdownTrackedChangetypeSource ↗

Normalized DOCX tracked change, independent of editor UI state.

Its ID is opaque and stable only within one [MarkdownExportResult](MarkdownExportResult). Never persist the ID across exports; pair citations with the caller's own document version or content hash.

type MarkdownTrackedChange = SemanticTrackedChangeArtifactRecord;

OpenDocumentForExportResulttype

Typed refusal for bytes that cannot become a document view, or an already-aborted open.

type OpenDocumentForExportResult = {
    readonly ok: true;
    readonly session: ExportSession;
} | {
    readonly ok: false;
    readonly reason: HeadlessDocumentRejection | 'aborted';
    readonly detail?: string;
};

OpenMarkdownDocumentForExportResulttypeSource ↗

Open result whose successful session retains its structured font-resolution report.

type OpenMarkdownDocumentForExportResult = {
    readonly ok: true;
    readonly session: MarkdownExportSession;
} | Exclude<OpenDocumentForExportResult, {
    readonly ok: true;
}>;

PreservedImageConvertertype

Optional caller conversion for preserved formats such as EMF/WMF/TIFF.

type PreservedImageConverter = (bytes: Uint8Array, mime: PreservedImageMime, limits: ImageResourceLimits, 
signal?: AbortSignal) => Promise<Readonly<{
    bytes: Uint8Array;
    mime: SupportedImageMime;
}> | null>;

RevisionDisplayModetype

Which revisions layout resolves before producing pages.

- all-markup shows both halves of every change. - proposed shows what the document becomes if every change is accepted. - original shows what it was before any of them.

The last two are specified as equal to accept-all and reject-all OUTPUT, which is what makes them testable, without either applying an op.

type RevisionDisplayMode = 'all-markup' | 'proposed' | 'original';

SemanticArtifactRootStoryKindtype

Published root story containing an artifact occurrence.

type SemanticArtifactRootStoryKind = 'body' | 'header' | 'footer' | 'footnote' | 'endnote' | 'note-separator';

SemanticArtifactStoryKindtype

Exact story in which a review artifact's source anchor was laid out.

type SemanticArtifactStoryKind = SemanticArtifactRootStoryKind | 'textbox';

SemanticReviewArtifactRecordtype

Exporter-neutral review artifact normalized by core.

type SemanticReviewArtifactRecord = SemanticTrackedChangeArtifactRecord | SemanticCommentArtifactRecord;

HARD_MAX_AGGREGATE_FONT_BYTESconst

Most bytes all admitted faces may total, whatever a caller configures.

HARD_MAX_AGGREGATE_FONT_BYTES: number

HARD_MAX_FONT_BYTESconst

Largest single face this engine will ever admit, whatever a caller configures.

A CEILING, not a default: a host may set a smaller maxFontBytes, but nothing can raise it past this. Font bytes come from files, and an unbounded face is a memory-exhaustion vector.

HARD_MAX_FONT_BYTES: number

HARD_MAX_FONT_SOURCESconst

Most faces one snapshot may hold, whatever a caller configures.

HARD_MAX_FONT_SOURCES = 256