markdown-docx

Convert Markdown files to DOCX format with support for both browser and Node.js environments.

将 Markdown 文件转换为 DOCX 格式，支持浏览器和 Node.js 环境。

Online Demo

Markdown to DOCX Converter

Features

• 📝 Convert Markdown to DOCX format with high fidelity
• 🖼️ Support for images (with automatic downloading)
• 📋 Support for tables, lists, code blocks, and other Markdown elements
• 🔗 Hyperlinks and footnotes support
• 💅 Customizable styling options
• 🌐 Works in both browser and Node.js environments
• 🖥️ Command-line interface available

Installation

# Using npm
npm install markdown-docx

# Using yarn
yarn add markdown-docx

# Using pnpm
pnpm add markdown-docx

Basic Usage

Node.js

import fs from 'node:fs/promises';
import markdownDocx, { Packer } from 'markdown-docx';

async function convertMarkdownToDocx() {
  // Read markdown content
  const markdown = await fs.readFile('input.md', 'utf-8');
  
  // Convert to docx
  const doc = await markdownDocx(markdown);
  
  // Save to file
  const buffer = await Packer.toBuffer(doc);
  await fs.writeFile('output.docx', buffer);
  
  console.log('Conversion completed successfully!');
}

convertMarkdownToDocx();

Browser

import markdownDocx, { Packer } from 'markdown-docx';

async function convertMarkdownToDocx(markdownText) {
  // Convert to docx
  const doc = await markdownDocx(markdownText);
  
  // Generate blob for download
  const blob = await Packer.toBlob(doc);
  
  // Create download link
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'document.docx';
  a.click();
  
  // Clean up
  URL.revokeObjectURL(url);
}

// Example usage with a textarea
document.getElementById('convert-btn').addEventListener('click', () => {
  const markdown = document.getElementById('markdown-input').value;
  convertMarkdownToDocx(markdown);
});

Advanced Usage

Using the MarkdownDocx Class

For more control over the conversion process, you can use the MarkdownDocx class directly:

import { MarkdownDocx, Packer } from 'markdown-docx';
import fs from 'node:fs/promises';

async function convertWithOptions() {
  const markdown = await fs.readFile('input.md', 'utf-8');
  
  // Create instance with options
  const converter = new MarkdownDocx(markdown)
  
  // Generate document
  const doc = await converter.toDocument({
    title: 'My Document',
    creator: 'markdown-docx',
    description: 'Generated from Markdown'
  });
  
  // Save to file
  const buffer = await Packer.toBuffer(doc);
  await fs.writeFile('output.docx', buffer);
}

Configuration Options

The MarkdownDocx constructor and markdownDocx function accept an options object with the following properties:

| Option | Type | Default | Description | |--------|------|---------|-------------| | imageAdapter | Function | Built-in adapter | Custom function to handle image processing | | ignoreImage | Boolean | false | When set to true, images in markdown will be ignored | | ignoreFootnote | Boolean | false | When set to true, footnotes will be ignored | | ignoreHtml | Boolean | false | When set to true, inline HTML will be ignored | | gfm | Boolean | true | Enable GitHub Flavored Markdown support |

Additional options from the marked library are also supported.

Command Line Interface

markdown-docx includes a CLI tool for converting markdown files from the command line:

# Install globally
npm install -g markdown-docx

# Basic usage
markdown-docx --input input.md --output output.docx

# Short form
markdown-docx -i input.md -o output.docx

If the output file is not specified, it will use the input filename with a .docx extension.

Supported Markdown Features

• Headings (H1-H6)
• Paragraphs and line breaks
• Emphasis (bold, italic, strikethrough)
• Lists (ordered and unordered)
• Links and images
• Blockquotes
• Code blocks
• Tables
• Horizontal rules
• Footnotes
• Task lists (checkboxes)

Image Adapter

The library provides a built-in image adapter that automatically downloads images from URLs. You can also create a custom image adapter by implementing the ImageAdapter interface. The adapter should have a getImage method that takes an image URL and returns a Promise that resolves to an object containing the image data.

const imageAdapter: (token: Tokens.Image) => Promise<null | MarkdownImageItem>

Customization

You can customize the styling of the generated DOCX by accessing the style components:

import { styles, colors, classes, numbering } from 'markdown-docx';

// Example: customize docs link color
styles.default.hyperlink.run.color = '0077cc';
styles.markdown.code.run.color = '000000';

You can refer to the files in src/styles to write your own styles.

• styles.ts - Default styles for the document
• colors.ts - Color definitions
• markdown.ts - Markdown-specific styles

Browser vs Node.js

The library automatically detects the environment and uses the appropriate image adapter:

• In the browser, images are fetched using the Fetch API
• In Node.js, images are downloaded using the built-in HTTP/HTTPS modules

Examples

For more examples, see the tests directory in the repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• docx - The underlying library for creating DOCX files
• marked - The Markdown parser used in this project