md-to-docx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

md-to-docx

Use this skill to reliably produce

.docx

output from Markdown.

使用该工具可将Markdown可靠转换为

.docx

格式输出。

Workflow

工作流程

Decide the execution mode:
- CLI mode for file-to-file conversion.
- Programmatic mode for app code integration.
Confirm input source (Markdown file or Markdown string).
Confirm output target (
```
.docx
```
file path or browser download).
Apply options only when requested (alignment, sizes, direction, font family, replacements, template, sections, page numbering).
Run conversion and report resulting output path or filename.

确定执行模式：
- CLI模式：用于文件到文件的转换。
- 程序化模式：用于集成到应用代码中。
确认输入源（Markdown文件或Markdown字符串）。
确认输出目标（
```
.docx
```
文件路径或浏览器下载）。
仅在用户要求时应用配置选项（对齐方式、尺寸、方向、字体族、文本替换、模板、章节、页码设置）。
执行转换并报告最终输出路径或文件名。

CLI Mode

CLI模式

Use these commands:

bash

npx @mohtasham/md-to-docx input.md output.docx
md-to-docx input.md output.docx
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
md-to-docx --help

CLI contract:

Required positional args:
```
<input.md> <output.docx>
```

Optional options file:

--options <options.json>

-o <options.json>

Options JSON can include the same shapes as the API:
```
style
```
,
```
template
```
,
```
sections
```
, and
```
textReplacements
```
Help flags:
```
-h
```
or
```
--help
```
On success, expect:
```
DOCX created at: <absolute-path>
```

使用以下命令：

bash

npx @mohtasham/md-to-docx input.md output.docx
md-to-docx input.md output.docx
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
md-to-docx --help

CLI约定：

必填位置参数：
```
<input.md> <output.docx>
```

可选配置文件：

--options <options.json>

或

-o <options.json>

配置JSON可包含与API相同的结构：
```
style
```
、
```
template
```
、
```
sections
```
和
```
textReplacements
```
帮助标识：
```
-h
```
或
```
--help
```
成功时会输出：
```
DOCX created at: <absolute-path>
```

Programmatic Mode

程序化模式

typescript

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

const markdown = "# Title\n\nHello **DOCX**.";
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Trebuchet MS",
    heading1Alignment: "CENTER",
    paragraphAlignment: "JUSTIFIED",
    codeBlockAlignment: "LEFT",
    direction: "LTR"
  }
});

downloadDocx(blob, "output.docx");

Use

convertMarkdownToDocx(markdown, options?)

to produce a DOCX

Blob

. Use

downloadDocx(blob, filename?)

only in browser environments.

typescript

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

const markdown = "# Title\n\nHello **DOCX**.";
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Trebuchet MS",
    heading1Alignment: "CENTER",
    paragraphAlignment: "JUSTIFIED",
    codeBlockAlignment: "LEFT",
    direction: "LTR"
  }
});

downloadDocx(blob, "output.docx");

使用

convertMarkdownToDocx(markdown, options?)

生成DOCX格式的

Blob

。仅在浏览器环境中使用

downloadDocx(blob, filename?)

。

Multi-Section Documents

多章节文档

Use

options.template

for shared defaults and

options.sections

for per-section markdown and overrides:

typescript

const blob = await convertMarkdownToDocx("", {
  template: {
    footers: {
      default: { pageNumberDisplay: "currentAndTotal", alignment: "CENTER" }
    }
  },
  sections: [
    {
      markdown: "# Cover Page\n\nIntroduction here.",
      titlePage: true,
      headers: { first: { text: "Confidential", alignment: "RIGHT" } },
      pageNumbering: { start: 1, display: "none" }
    },
    {
      markdown: "# Chapter 1\n\nBody content.",
      style: { paragraphAlignment: "JUSTIFIED" },
      pageNumbering: { start: 1, display: "currentAndTotal" }
    }
  ]
});

Each section can override:

style

headers

footers

pageNumbering

page

(margins/size/orientation),

titlePage

, and

type

(break type).

Merge precedence:

Global
```
style
```
applies first
```
template
```
provides shared section defaults
Per-section options win last

Use

pageNumbering.display

for common footer numbering modes:

none

current

currentAndTotal

, or

currentAndSectionTotal

使用

options.template

设置全局默认配置，

options.sections

为各章节设置独立的Markdown内容和覆盖配置：

typescript

const blob = await convertMarkdownToDocx("", {
  template: {
    footers: {
      default: { pageNumberDisplay: "currentAndTotal", alignment: "CENTER" }
    }
  },
  sections: [
    {
      markdown: "# Cover Page\n\nIntroduction here.",
      titlePage: true,
      headers: { first: { text: "Confidential", alignment: "RIGHT" } },
      pageNumbering: { start: 1, display: "none" }
    },
    {
      markdown: "# Chapter 1\n\nBody content.",
      style: { paragraphAlignment: "JUSTIFIED" },
      pageNumbering: { start: 1, display: "currentAndTotal" }
    }
  ]
});

每个章节可覆盖以下配置：

style

、

headers

、

footers

、

pageNumbering

、

page

（边距/尺寸/方向）、

titlePage

和

type

（分页类型）。

配置优先级：

全局
```
style
```
优先生效
```
template
```
提供章节共享默认值
章节独立配置优先级最高

使用

pageNumbering.display

设置常见页脚页码模式：

none

、

current

、

currentAndTotal

或

currentAndSectionTotal

。

Text Replacements

文本替换

Use

textReplacements

to rewrite text before conversion:

typescript

const blob = await convertMarkdownToDocx("# Hello oldText", {
  textReplacements: [
    { find: /oldText/g, replace: "newText" },
    { find: "Hello", replace: "Hi" }
  ]
});

使用

textReplacements

在转换前重写文本内容：

typescript

const blob = await convertMarkdownToDocx("# Hello oldText", {
  textReplacements: [
    { find: /oldText/g, replace: "newText" },
    { find: "Hello", replace: "Hi" }
  ]
});

Markdown Features to Expect

支持的Markdown特性

Support includes:

Headings
```
#
```
to
```
#####
```
Ordered/unordered lists
Bold, italic, underline (
```
++text++
```
), strikethrough (
```
~~text~~
```
)
Custom font family via
```
fontFamily
```
style option
Blockquotes
Tables (with inline formatting: bold, italic, code, links, strikethrough in cells)
Code blocks and inline code (with configurable
```
codeBlockAlignment
```
)
Links and images
Text replacements before rendering via
```
textReplacements
```
```
COMMENT: ...
```
```
[TOC]
```
on its own line
```
\pagebreak
```
on its own line
Horizontal rules (
```
---
```
) are skipped during DOCX generation

支持特性包括：

标题
```
#
```
至
```
#####
```
有序/无序列表
粗体、斜体、下划线（
```
++text++
```
）、删除线（
```
~~text~~
```
）
通过
```
fontFamily
```
样式选项设置自定义字体族
块引用
表格（单元格内支持粗体、斜体、代码、链接、删除线等格式）
代码块和行内代码（可配置
```
codeBlockAlignment
```
）
链接和图片
渲染前通过
```
textReplacements
```
替换文本
```
COMMENT: ...
```
注释
单独一行的
```
[TOC]
```
目录标记
单独一行的
```
\pagebreak
```
分页符
水平线（
```
---
```
）在DOCX生成过程中会被忽略

Style Options Quick Reference

样式选项速查

Option	Values	Default
`paragraphAlignment`	`LEFT` , `CENTER` , `RIGHT` , `JUSTIFIED`	`LEFT`
`headingAlignment`	same	`LEFT`
`heading1Alignment` – `heading5Alignment`	same	`LEFT`
`blockquoteAlignment`	same	`LEFT`
`codeBlockAlignment`	same	`LEFT`
`fontFamily`	any font name string	`Calibri`
`direction`	`LTR` , `RTL`	`LTR`
`tableLayout`	`autofit` , `fixed`	`autofit`
`tocFontSize`	number	library default

选项	可选值	默认值
`paragraphAlignment`	`LEFT` , `CENTER` , `RIGHT` , `JUSTIFIED`	`LEFT`
`headingAlignment`	同上	`LEFT`
`heading1Alignment` – `heading5Alignment`	同上	`LEFT`
`blockquoteAlignment`	同上	`LEFT`
`codeBlockAlignment`	同上	`LEFT`
`fontFamily`	任意字体名称字符串	`Calibri`
`direction`	`LTR` , `RTL`	`LTR`
`tableLayout`	`autofit` , `fixed`	`autofit`
`tocFontSize`	数字	库默认值

Troubleshooting

故障排查

If CLI fails with argument errors, re-check that exactly two positional paths are provided.
If options parsing fails, validate JSON syntax and ensure the root is an object.
If output is missing, verify destination directory permissions and path spelling.
If in Node and you need a file, write the returned
```
Blob
```
bytes to disk instead of using
```
downloadDocx
```
.
If sections produce unexpected numbering, ensure each section sets
```
pageNumbering.start
```
to reset counts.
If first-page headers or footers do not appear, set
```
titlePage: true
```
on that section.

若CLI因参数错误失败，请检查是否提供了恰好两个位置路径参数。
若配置解析失败，请验证JSON语法并确保根结构为对象。
若输出文件缺失，请检查目标目录权限和路径拼写。
若在Node环境中需要生成文件，请将返回的
```
Blob
```
字节写入磁盘，而非使用
```
downloadDocx
```
。
若章节页码显示异常，请确保每个章节设置
```
pageNumbering.start
```
来重置计数。
若首页页眉或页脚未显示，请为该章节设置
```
titlePage: true
```
。