https://github.com/inokawa/remark-docx
remark plugin to compile markdown to docx (Microsoft Word, Office Open XML).
https://github.com/inokawa/remark-docx
docx latex markdown math mdast office openxml remark remark-plugin unified word
Last synced: about 2 months ago
JSON representation
remark plugin to compile markdown to docx (Microsoft Word, Office Open XML).
- Host: GitHub
- URL: https://github.com/inokawa/remark-docx
- Owner: inokawa
- License: mit
- Created: 2022-01-08T09:31:03.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-03T16:52:10.000Z (12 months ago)
- Last Synced: 2025-03-28T14:11:11.227Z (11 months ago)
- Topics: docx, latex, markdown, math, mdast, office, openxml, remark, remark-plugin, unified, word
- Language: TypeScript
- Homepage: https://inokawa.github.io/remark-docx/
- Size: 19.8 MB
- Stars: 63
- Watchers: 9
- Forks: 17
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# remark-docx
   
> [remark](https://github.com/remarkjs/remark) plugin to compile markdown to docx (Microsoft Word, Office Open XML).
- Uses [docx](https://github.com/dolanmiu/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](https://github.com/syntax-tree/mdast) nodes
Currently, some of the default styles may not be nice. If you have feature requests or improvements, please create a [issue](https://github.com/inokawa/remark-docx/issues) or [PR](https://github.com/inokawa/remark-docx/pulls).
- [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](#image))
- [x] html ([plugin](#html))
- [x] code ([plugin](#code))
- [x] math / inlineMath ([remark-math](https://github.com/remarkjs/remark-math) and [plugin](#math))
## Demo
https://inokawa.github.io/remark-docx/
## Install
```sh
npm install remark-docx
```
## Getting started
### Browser
```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");
})();
```
### Node.js
```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
### Image
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](https://developer.mozilla.org/docs/Web/API/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;
},
});
```
### Code
#### Syntax highlight
Syntax highlighting with [shiki](https://github.com/shikijs/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](https://mermaid.js.org/) 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()] });
```
### Math
Render LaTeX with [MathJax](https://github.com/mathjax/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()] });
```
### HTML
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](./docs/API.md)
## Contribute
All contributions are welcome.
If you find a problem, feel free to create an [issue](https://github.com/inokawa/remark-docx/issues) or a [PR](https://github.com/inokawa/remark-docx/pulls).
### 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](https://github.com/inokawa/remark-slate-transformer)
- [remark-pdf](https://github.com/inokawa/remark-pdf)