remark-docx

!npm !npm !check !demo

> 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.

$3

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

``sh
npm install remark-docx
`

Getting started

$3

`javascript
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");
})();
`

$3

`javascript
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

$3

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

`javascript
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.

`javascript
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.

`javascript
import sharp from "sharp";

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

$3

#### Syntax highlight

Syntax highlighting with shiki.

`javascript
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.

`javascript
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()] });
`

$3

Render LaTeX with MathJax.

`javascript
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()] });
`

$3

Transform HTML to markdown.

`javascript
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.

$3

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