How to convert Markdown to Word with @mohtasham/md-to-docx

npm install @mohtasham/md-to-docx
# or
pnpm add @mohtasham/md-to-docx
# or
bun add @mohtasham/md-to-docx
# or
yarn add @mohtasham/md-to-docx

[TOC]

# Product reliability report

Prepared for the engineering team.

## Summary

The API handled **99.95%** of requests successfully this month.

## Results

| Metric | Result |
| --- | ---: |
| Availability | 99.95% |
| p95 latency | 184 ms |
| Incidents | 2 |

: Monthly service results {#tbl:service-results}

The full results appear in [@tbl:service-results].

\pagebreak

## Next actions

1. Move image processing to a worker.
2. Add an alert for queue depth.
3. Repeat the load test after deployment.

npx @mohtasham/md-to-docx report.md report.docx

bunx @mohtasham/md-to-docx report.md report.docx

npm install -g @mohtasham/md-to-docx
md-to-docx report.md report.docx

{
  "documentType": "report",
  "style": {
    "fontFamily": "Aptos",
    "heading1Alignment": "LEFT",
    "paragraphAlignment": "JUSTIFIED",
    "tableLayout": "fixed"
  },
  "toc": {
    "title": "Contents",
    "minDepth": 1,
    "maxDepth": 3
  },
  "codeHighlighting": {
    "enabled": true,
    "showLanguageLabel": true
  }
}

md-to-docx report.md report.docx --options options.json
md-to-docx report.md report.docx -o options.json

import { readFile, writeFile } from "node:fs/promises";
import { convertMarkdownToBuffer } from "@mohtasham/md-to-docx";

const markdown = await readFile("report.md", "utf8");

const output = await convertMarkdownToBuffer(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Aptos",
    paragraphAlignment: "JUSTIFIED",
  },
  metadata: {
    title: "Product reliability report",
    creator: "Engineering Team",
    language: "en-GB",
  },
});

await writeFile("report.docx", output);

"use client";

import { useState } from "react";
import {
  convertMarkdownToDocx,
  downloadDocx,
} from "@mohtasham/md-to-docx";

export function WordExport() {
  const [markdown, setMarkdown] = useState("# Untitled document");

  async function exportDocument() {
    const blob = await convertMarkdownToDocx(markdown, {
      style: { fontFamily: "Aptos" },
    });

    await downloadDocx(blob, "document.docx");
  }

  return (
    <div>
      <textarea
        value={markdown}
        onChange={(event) => setMarkdown(event.target.value)}
      />
      <button onClick={exportDocument}>Download Word file</button>
    </div>
  );
}

> [!NOTE]
> This paragraph becomes a Word callout.

<!-- COMMENT: Confirm this number before sending. -->

The request path is shown in [@fig:request-flow].

![Request flow from the browser to the worker](request-flow.png)

: Request processing flow {#fig:request-flow}

| Stage | p95 |
| --- | ---: |
| API | 184 ms |
| Worker | 420 ms |

: Processing latency {#tbl:latency}

const options = {
  captions: {
    figureLabel: "Diagram",
    tableLabel: "Dataset",
    figurePlacement: "below",
    tablePlacement: "above",
    alignment: "CENTER",
    failureMode: "throw",
  },
};

import type { Options } from "@mohtasham/md-to-docx";

const options: Options = {
  documentType: "report",
  style: {
    fontFamily: "Aptos",
    heading1Size: 32,
    heading2Size: 28,
    paragraphSize: 24,
    paragraphAlignment: "JUSTIFIED",
    headingAlignment: "LEFT",
    codeBlockAlignment: "LEFT",
    direction: "LTR",
    tableLayout: "fixed",
  },
  textReplacements: [
    { find: "ACME", replace: "Acme Corporation" },
    { find: /DRAFT/g, replace: "INTERNAL" },
  ],
};

import { writeFile } from "node:fs/promises";
import { convertMarkdownToBuffer } from "@mohtasham/md-to-docx";

const output = await convertMarkdownToBuffer("", {
  style: {
    fontFamily: "Aptos",
    paragraphSize: 24,
  },
  template: {
    pageNumbering: {
      display: "currentAndTotal",
      alignment: "CENTER",
    },
  },
  sections: [
    {
      markdown: "# Product reliability report\n\nPrepared for the engineering team.",
      titlePage: true,
      footers: { default: null },
      pageNumbering: { display: "none" },
      style: { paragraphAlignment: "CENTER" },
    },
    {
      markdown: "[TOC]\n\n# Summary\n\nMain report content.",
      headers: {
        default: {
          text: "Reliability report",
          alignment: "RIGHT",
        },
      },
      pageNumbering: {
        start: 1,
        display: "currentAndTotal",
      },
    },
    {
      markdown: "# Appendix\n\nWide tables belong here.",
      type: "NEXT_PAGE",
      page: {
        size: { orientation: "LANDSCAPE" },
      },
    },
  ],
});

await writeFile("sectioned-report.docx", output);

import { readFile, writeFile } from "node:fs/promises";
import {
  convertMarkdownWithReferenceDocxToBuffer,
} from "@mohtasham/md-to-docx";

const reference = await readFile("company-reference.docx");
const markdown = await readFile("report.md", "utf8");

const output = await convertMarkdownWithReferenceDocxToBuffer(
  markdown,
  reference,
  {
    reference: {
      styles: {
        normal: { name: "Corporate Body" },
        heading1: { id: "CorpHeading1" },
        table: { name: "Corporate Table" },
      },
      preservePageLayout: true,
      preserveHeadersAndFooters: true,
    },
  },
);

await writeFile("styled-report.docx", output);

import { readFile, writeFile } from "node:fs/promises";
import { patchMarkdownInDocxToBuffer } from "@mohtasham/md-to-docx";

const template = await readFile("company-template.docx");

const output = await patchMarkdownInDocxToBuffer(
  template,
  {
    body: "# Quarterly update\n\nRevenue increased **18%**.",
    appendix: "## Appendix\n\nSupporting notes.",
  },
  {
    keepOriginalStyles: true,
    style: { fontFamily: "Aptos" },
  },
);

await writeFile("completed-template.docx", output);

const options = {
  metadata: {
    title: "Product reliability report",
    subject: "Monthly API review",
    creator: "Engineering Team",
    keywords: ["reliability", "API", "operations"],
    company: "Acme Corporation",
    language: "en-GB",
    custom: {
      ReviewState: "Draft",
      Build: "2026.08",
    },
  },
  accessibility: {
    missingImageAltText: "throw",
  },
};

const options = {
  codeHighlighting: {
    enabled: true,
    showLanguageLabel: true,
    languages: ["typescript", "javascript", "python", "bash"],
  },
};

The failure rate is $r = \frac{f}{n}$.

$$
\sum_{i=1}^{n} x_i
$$

const options = {
  chartRendering: {
    enabled: true,
    width: 640,
    height: 360,
  },
};

```chart
{
  "type": "bar",
  "data": {
    "labels": ["May", "June", "July"],
    "datasets": [
      {
        "label": "Incidents",
        "data": [5, 3, 2]
      }
    ]
  },
  "alt": "Incidents fell from five in May to two in July"
}
```

const options = {
  mermaidRendering: {
    enabled: true,
    render: async ({ code, signal }) => {
      const image = await renderMermaidToPng(code, { signal });
      return {
        data: image,
        contentType: "image/png",
        width: 640,
        altText: "Request flow through the API and worker",
      };
    },
  },
};

npx skills add MohtashamMurshid/md-to-docx

npx skills add MohtashamMurshid/md-to-docx --list --full-depth

Convert report.md to report.docx. Use Aptos, justify body paragraphs,
add a table of contents, and put Page X of Y in the footer.