inokawa / remark-docx

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

remark-docx

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

🚧 WIP 🚧

This project is aiming to support all nodes in mdast syntax tree, but currently transformation and stylings may not be well.

If you have some feature requests or improvements, please create a issue or PR.

• paragraph
• heading
• thematicBreak
• blockquote
• list
• listItem
• table
• tableRow
• tableCell
• html
• code
• yaml
• toml
• definition
• footnoteDefinition
• text
• emphasis
• strong
• delete
• inlineCode
• break
• link
• image
• linkReference
• imageReference
• footnote
• footnoteReference
• LaTeX support with math and inlineMath (remark-math is required)

Demo

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

Install

npm install remark-docx

Usage

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, { output: "blob" });

const text = "# hello world";

(async () => {
  const doc = await processor.process(text);
  const blob = await doc.result;
  saveAs(blob, "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, { output: "buffer" });

const text = "# hello world";

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

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

remark-docx's Issues

Paragraph margin bottom

First of all, thank you very much, @inokawa for this awesome library!

Is your feature request related to a problem? Please describe.
Yes, I've tried the demo which worked very nicely. However, it seems that there currently is no option to add some space between paragraphs.

Describe the solution you'd like
A styling option for the whole document to apply e.g. 20px of space below every paragraph.

Describe alternatives you've considered
I've tried to add markdown Break and ThematicBreak but it is not the ideal solution.

Possible solution
It might be possible to add the spacing parameter (after) here like described in this documentation, and set it to a configurable value.

I unfortunately can't implement it myself currently due to lack of time but if this is still open later I'd give it a try.

import issues

Describe the bug
When I made the PR I tested using the storybook app, now Im trying to use in another application and getting errors:
if I try the default import:

import docx from "remark-docx";

// error
C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\remark-docx@0.1.2\node_modules\remark-docx\lib\index.js:4
var unistUtilVisit = require('unist-util-visit');       
                     ^

Error [ERR_REQUIRE_ESM]: require() of ES Module C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\unist-util-visit@4.1.2\node_modules\unist-util-visit\index.js from C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\remark-docx@0.1.2\node_modules\remark-docx\lib\index.js not supported.
Instead change the require of C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\unist-util-visit@4.1.2\node_modules\unist-util-visit\index.js in C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\remark-docx@0.1.2\node_modules\remark-docx\lib\index.js to a dynamic import() which is available in all CommonJS modules.
    at Object.<anonymous> (C:\Users\55119\Elucidário.art\elucidario\node_modules\.pnpm\remark-docx@0.1.2\node_modules\remark-docx\lib\index.js:4:22)
    at async Promise.all (index 0) {
  code: 'ERR_REQUIRE_ESM'
}

Node.js v18.12.1
 ELIFECYCLE  Command failed with exit code 1.

if I try to import the mjs module:

import docx from "remark-docx/lib/index.mjs";

// error
file:///C:/Users/55119/Elucid%C3%A1rio.art/elucidario/node_modules/.pnpm/[email protected]/node_modules/remark-docx/lib/index.mjs:4
import { convertInchesToTwip, Packer } from 'docx';     
                              ^^^^^^
SyntaxError: Named export 'Packer' not found. The requested module 'docx' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'docx';
const { convertInchesToTwip, Packer } = pkg;

    at ModuleJob._instantiate (node:internal/modules/esm/module_job:123:21)
    at async ModuleJob.run (node:internal/modules/esm/module_job:189:5)
    at async Promise.all (index 0)
    at async ESMLoader.import (node:internal/modules/esm/loader:530:24)
    at async loadESM (node:internal/process/esm_loader:91:5)
    at async handleMainPromise (node:internal/modules/run_main:65:12)

Node.js v18.12.1
 ELIFECYCLE  Command failed with exit code 1.

Support start field of List

https://github.com/syntax-tree/mdast#list

Add docx to remark plugin

Is your feature request related to a problem? Please describe.
docx to remark conversion may be useful in some cases.

Describe the solution you'd like
https://github.com/lalalic/docx4js

Describe alternatives you've considered
Nothing.

Additional context
Nothing.

footnotes?

Describe the solution you'd like
footnotes would be awesome

Still maintained ?

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Awaiting Schedule

These updates are awaiting their schedule. Click on a checkbox to get an update now.

• Update babel monorepo to v7.21.4 (@babel/core, @babel/preset-env, @babel/preset-typescript)
• Update dependency @unified-latex/unified-latex-util-parse to v1.3.1
• Update dependency docx to v7.8.2
• Update dependency rollup to v2.79.1
• Update dependency tslib to v2.5.0
• Update dependency typedoc to v0.24.4
• Update dependency typedoc-plugin-markdown to v3.15.2
• Update dependency typescript to v4.9.5
• Update dependency webpack to v5.80.0
• Update jest monorepo to v29.5.0 (babel-jest, jest)
• Update actions/cache action to v3
• Update actions/checkout action to v3
• Update dependency @rollup/plugin-typescript to v11
• Update dependency docx to v8
• Update dependency rimraf to v5
• Update dependency rollup to v3
• Update dependency typescript to v5
• Update storybook monorepo to v7 (major) (@storybook/addon-essentials, @storybook/builder-webpack5, @storybook/react)

Detected dependencies

github-actions

.github/workflows/check.yml

• actions/checkout v2
• actions/setup-node v3
• actions/cache v2

.github/workflows/demo.yml

• actions/checkout v2
• actions/setup-node v3
• actions/cache v2
• peaceiris/actions-gh-pages v3

npm

package.json

• @unified-latex/unified-latex-util-parse 1.0.12
• docx ^7.4.1
• unist-util-visit ^4.1.0
• @babel/core 7.20.12
• @babel/preset-env 7.20.2
• @babel/preset-typescript 7.18.6
• @rollup/plugin-typescript 8.5.0
• @storybook/addon-essentials 6.5.16
• @storybook/builder-webpack5 6.5.16
• @storybook/manager-webpack5 6.5.16
• @storybook/react 6.5.16
• @types/adm-zip ^0.5.0
• @types/mdast ^3.0.10
• @types/unist 2.0.6
• adm-zip ^0.5.9
• babel-jest 29.0.2
• docx-preview 0.1.15
• file-saver ^2.0.5
• jest 29.0.2
• react 18.2.0
• react-dom 18.2.0
• react-is 18.2.0
• remark-footnotes 4.0.1
• remark-frontmatter 4.0.1
• remark-gfm 3.0.1
• remark-math 5.1.1
• remark-parse 10.0.1
• rimraf 3.0.2
• rollup 2.76.0
• tslib 2.4.1
• typedoc 0.23.28
• typedoc-plugin-markdown 3.14.0
• typescript 4.7.4
• unified 10.1.2
• webpack 5.76.0

---

• Check this box to trigger a request for Renovate to run again on this repository

Add paraIds to w:p elements

Is your feature request related to a problem? Please describe.
In our app I am relying on paraIds ("w14:paraId" attributes) to identify specific w:p elements in the docx file and apply changes to them. Docx files from Word or Google Docs do contain these attributes. Docx files generated with remark-docx do not seem to have paraIds.

Describe the solution you'd like
Generate ids for each w:p element and add them as w14:paraId attributes.

Describe alternatives you've considered
Right now I have to postprocess the docx file to add the paraIds in our own code.

Add more options to style

• page
• paragraph
• text

Table Formatting

Hi - Thanks for making this library. It's great! I have a question. I am trying to format a table where the conversion to docx format occurs on the server (node). I am using remark-gfm to create the table, but it has no style. Is it possible to pass docx table styles into remark-docx?

So far, I think docx doesn't provide the ability to edit, outside of the patcher which only lets you add things. However, I have a table in the middle of the markdown. Also, it doesn't look like docx style options like paragraphStyles, default , or document styles accept options formatting tables. As far as I can tell, it seems like table styles must be passed into docx when the table is created new Table, new Row, and new Cell. So, if I understand everything correctly, if there were to be table styles, they'd have to be applied when the table is created within remark-docx.

Any ideas on how that might work? Thanks!

  const processor = unified()
    .use(remarkParse)
    .use(markdown)
    .use(remarkBreaks)
    .use(remarkGfm)
    .use(docx, { output: 'buffer', styles });

Make default style pretty

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

Sections

Describe the solution you'd like
Split the document into sections.

Describe alternatives you've considered
hello there, happy new year!
I was wondering if we could discuss a way to implement sections into the plugin.
I can visualize two possible paths:

1 - Pass an array of SectionTuple to mdastToDocx which in turns pass to convertNodes at the ctx param:

type SectionTuple = [title: string; type?: CONTINUOUS | EVEN_PAGE | NEXT_COLUMN | NEXT_PAGE | ODD_PAGE ];

const sectionsTuples: SectionTuple[] = [
    ["Introduction", EVEN_PAGE],
    ["Chapter 1"],
    ["Chapter 2"],
    ["Conclusion", NEXT_PAGE]
    ["Bibliography", EVEN_PAGE]
]

Then convertNodes return a reduced array of sections based on title and page heading:

const { nodes, footnotes, sections } = convertNodes(node.chidlren, {
    deco: {},
    images,
    indent: 0,
    sections: sectionsTuples,
})

The sectionsTuples should not be required, and the convertNodes function should still return the nodes as is in a standard way.

2 - Implement a frontmatter definition. For that we would need to finish the implementation of yaml and toml:

---
section: introduction
section_type: EVEN_PAGE
---

# Introduction

I believe that going both ways in parallel would be cool as it would add more versatility to the plugin. What do you think about?

Math support

Would be nice if LaTeX math could be exported to docx. Are there any plans to go in that direction?

Support spread field of List

https://github.com/syntax-tree/mdast#list

Add htmls tag

aaaaa

Tables not working

Describe the bug
My markdown containing table does not convert to table in docx.

To Reproduce

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, { output: "blob" });

export const saveMessage = async () => {

  const html = `
| Column 1 |Column 2| Column 3 |
| -------- |--------| -------- |
| Row 1    | Data     | Data   |
| Row 2    | Data     | Data   |
| Row 3    | Data     | Data   |
`
  const doc = await processor.process(html);
  const blob = await doc.result as Blob;
  saveAs(blob, "example.docx");
}

saveMessage()

The example.docx file

Same string in the playground

Expected behavior
To be a table in the docx.

Additional context
"remark-docx": "^0.1.6"
"file-saver": "^2.0.5"