remark-docx

remark plugin to compile markdown to docx (Microsoft Word, Office Open XML).

• Uses docx for compilation.
• Works in any environment (e.g. browser, Node.js).
• Provides reasonable default style and also tunable enough (WIP).
• Supports advanced layouts (RTL, vertical, 2 columns).
• Has own plugin system. You can fully customize markdown to Word transformation.

Supported mdast nodes

Currently, some of the default styles may not be nice. If you have feature requests or improvements, please create a issue or PR.

• [x] paragraph
• [x] heading
• [x] thematicBreak (rendered as Page Break / Section Break / Horizontal line)
• [x] blockquote
• [x] list / listItem
• [x] table / tableRow / tableCell
• [x] definition
• [x] text
• [x] emphasis
• [x] strong
• [x] delete
• [x] inlineCode
• [x] break
• [x] link / linkReference
• [x] footnoteReference / footnoteDefinition
• [x] image / imageReference (plugin)
• [x] html (plugin)
• [x] code (plugin)
• [x] math / inlineMath (remark-math and plugin)

Demo

https://inokawa.github.io/remark-docx/

Install

npm install remark-docx

Getting started

Browser

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import { saveAs } from "file-saver";

const processor = unified().use(markdown).use(docx);

const text = "# hello world";

(async () => {
  const doc = await processor.process(text);
  const arrayBuffer = await doc.result;
  saveAs(new Blob([arrayBuffer]), "example.docx");
})();

Node.js

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import * as fs from "fs";

const processor = unified().use(markdown).use(docx);

const text = "# hello world";

(async () => {
  const doc = await processor.process(text);
  const arrayBuffer = await doc.result;
  fs.writeFileSync("example.docx", Buffer.from(arrayBuffer));
})();

Plugins

Image

Fetch image data and embed into docx. png, jpg, gif, bmp, svg urls are supported.

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import { imagePlugin } from "remark-docx/plugins/image";

const processor = unified()
  .use(markdown)
  .use(docx, { plugins: [imagePlugin()] });

URLs are resolved with fetch API by default. You can use other methods such as file system.

import * as fs from "fs/promises";

imagePlugin({
  load: async (url) => {
    return (await fs.readFile(url)).buffer;
  },
});

When we embed svg to docx, it also requires png image since legacy Word can't render svg. On browser, this plugin generate it automatically. On other enviroment like Node.js, please implement fallbackSvg prop.

import sharp from "sharp";

imagePlugin({
  fallbackSvg: async ({ buffer }) => {
    return (await sharp(buffer).png().toBuffer()).buffer;
  },
});

Code

Syntax highlight

Syntax highlighting with shiki.

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import { shikiPlugin } from "remark-docx/plugins/shiki";

const processor = unified()
  .use(markdown)
  .use(docx, { plugins: [shikiPlugin({ theme: "dark-plus" })] });

Mermaid

Render Mermaid in code blocks with mermaid language. It only works in browser for now.

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import { mermaidPlugin } from "remark-docx/plugins/mermaid";

const processor = unified()
  .use(markdown)
  .use(docx, { plugins: [mermaidPlugin()] });

Math

Render LaTeX with MathJax.

import { unified } from "unified";
import markdown from "remark-parse";
import math from "remark-math";
import docx from "remark-docx";
import { latexPlugin } from "remark-docx/plugins/latex";

const processor = unified()
  .use(markdown)
  .use(math)
  .use(docx, { plugins: [latexPlugin()] });

HTML

Transform HTML to markdown.

import { unified } from "unified";
import markdown from "remark-parse";
import docx from "remark-docx";
import { htmlPlugin } from "remark-docx/plugins/html";

const processor = unified()
  .use(markdown)
  .use(docx, { plugins: [htmlPlugin()] });

Documentation

• API reference

Contribute

All contributions are welcome. If you find a problem, feel free to create an issue or a PR.

Making a Pull Request

1. Fork this repo.
2. Run npm install.
3. Commit your fix.
4. Add tests to cover the fix.
5. Make a PR and confirm all the CI checks passed.

Related projects

• remark-slate-transformer
• remark-pdf