@mohtasham/md-to-docx NPM

Markdown to DOCX Converter

A powerful TypeScript module that converts Markdown text to Microsoft Word (.docx) documents with support for various Markdown features. Perfect for both Node.js and browser environments.

Github Repo (Open Source)

https://github.com/MohtashamMurshid/md-to-docx

Features

🎯 Convert Markdown to DOCX format
📚 Table of Contents generation with clickable links ([TOC])
📄 Page break support (\pagebreak)
#️⃣ Automatic page numbering (centered in footer)
📝 Support for all heading levels (H1-H5)
📋 Bullet points and numbered lists with rich formatting
📊 Tables with headers and data
🔤 Bold and italic text formatting (including in lists)
💬 Blockquotes
💡 Comments
🎨 Customizable styling
📄 Report and document modes
🌐 Browser and Node.js support
🖼️ Support for embedded images
💻 Code blocks (inline and multi-line)
🔗 Support for links
~~Strikethrough~~ text support
📏 Custom font sizes for all elements
⚖️ Text alignment control for all elements
🧪 Comprehensive test coverage

Installation

npm install @mohtasham/md-to-docx

Usage

Basic Usage

import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const markdown = `
# Title
## Subtitle
This is a paragraph with **bold** and *italic* text.

- Bullet point with **bold text** inside
- Another point with *italic* and \`code\`
  **Bold text on next line**

1. Numbered item with **bold** formatting
2. Another item with mixed **bold** and *italic*

> This is a blockquote

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

\`\`\`typescript
function hello(name: string): string {
  return \`Hello, \${name}!\`;
}
\`\`\`

![Test Image](https://picsum.photos/200/200)

COMMENT: This is a comment
`;

// Convert to DOCX
const blob = await convertMarkdownToDocx(markdown);

// Download in browser
downloadDocx(blob, "output.docx");

With Custom Options

const options = {
  documentType: "report", // or 'document'
  style: {
    titleSize: 32,
    headingSpacing: 240,
    paragraphSpacing: 240,
    lineSpacing: 1.15,
    heading1Size: 32,
    heading2Size: 28,
    heading3Size: 24,
    heading4Size: 20,
    heading5Size: 18,
    paragraphSize: 24,
    listItemSize: 24,
    codeBlockSize: 20,
    blockquoteSize: 24,
    tocFontSize: 22, // Custom font size for TOC entries
    paragraphAlignment: "JUSTIFIED",
    blockquoteAlignment: "CENTER",
  },
};

const blob = await convertMarkdownToDocx(markdown, options);

Custom Table of Contents Styling

const options = {
  documentType: "document",
  style: {
    // Regular document styling
    titleSize: 32,
    headingSpacing: 240,
    paragraphSpacing: 240,

    // Custom TOC styling for each heading level
    tocHeading1FontSize: 28,
    tocHeading1Bold: true,
    tocHeading1Italic: false,

    tocHeading2FontSize: 24,
    tocHeading2Bold: true,
    tocHeading2Italic: false,

    tocHeading3FontSize: 22,
    tocHeading3Bold: false,
    tocHeading3Italic: false,

    tocHeading4FontSize: 20,
    tocHeading4Bold: false,
    tocHeading4Italic: true,

    tocHeading5FontSize: 18,
    tocHeading5Bold: false,
    tocHeading5Italic: true,
  },
};

const blob = await convertMarkdownToDocx(markdownWithToc, options);

Text Alignment Example

const markdownWithAlignment = `
# Left-Aligned Heading 1

## Left-Aligned Heading 2

This is a justified paragraph that demonstrates how text can be spread evenly across the width of the page. This creates a clean, professional look with straight edges on both the left and right margins.

> This is a centered blockquote that stands out from the regular text.

This is a left-aligned paragraph (default alignment) that shows the standard text positioning.
`;

const alignmentOptions = {
  documentType: "document",
  style: {
    paragraphAlignment: "JUSTIFIED",
    blockquoteAlignment: "CENTER",
    // All headings default to LEFT alignment
  },
};

const blob = await convertMarkdownToDocx(
  markdownWithAlignment,
  alignmentOptions
);

Custom Heading Alignments

You can customize the alignment for each heading level individually:

const customHeadingOptions = {
  documentType: "document",
  style: {
    // Individual heading alignments
    heading1Alignment: "CENTER", // H1 will be centered
    heading2Alignment: "RIGHT", // H2 will be right-aligned
    heading3Alignment: "JUSTIFIED", // H3 will be justified
    heading4Alignment: "LEFT", // H4 will be left-aligned
    heading5Alignment: "CENTER", // H5 will be centered

    // Other style options
    paragraphAlignment: "LEFT", // Paragraphs will be left-aligned
    blockquoteAlignment: "LEFT", // Blockquotes will be left-aligned
  },
};

const markdown = `
# This will be centered
## This will be right-aligned
### This will be justified
#### This will be left-aligned
##### This will be centered
`;

const blob = await convertMarkdownToDocx(markdown, customHeadingOptions);

In React

import { useState } from "react";
import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

function MarkdownConverter() {
  const [markdown, setMarkdown] = useState("");

  const handleConvert = async () => {
    try {
      const blob = await convertMarkdownToDocx(markdown);
      downloadDocx(blob, "converted.docx");
    } catch (error) {
      console.error("Conversion failed:", error);
    }
  };

  return (
    <div>
      <textarea
        value={markdown}
        onChange={(e) => setMarkdown(e.target.value)}
      />
      <button onClick={handleConvert}>Convert to DOCX</button>
    </div>
  );
}

API

`convertMarkdownToDocx(markdown: string, options?: Options): Promise<Blob>`

Converts Markdown text to a DOCX document.

Parameters

markdown (string): The Markdown text to convert
options (object, optional): Configuration options
- documentType (string): Either 'document' or 'report'
- style (object): Styling options
  - Text Sizes:
    - titleSize (number): Font size for titles
    - heading1Size through heading5Size (number): Font sizes for H1-H5
    - paragraphSize (number): Font size for paragraphs
    - listItemSize (number): Font size for list items
    - codeBlockSize (number): Font size for code blocks
    - blockquoteSize (number): Font size for blockquotes
    - tocFontSize (number): Font size for Table of Contents entries
    - tocHeading1FontSize through tocHeading5FontSize (number): Font sizes for specific heading levels in TOC
    - tocHeading1Bold through tocHeading5Bold (boolean): Whether specific heading levels in TOC should be bold
    - tocHeading1Italic through tocHeading5Italic (boolean): Whether specific heading levels in TOC should be italic
  - Spacing:
    - headingSpacing (number): Spacing before/after headings
    - paragraphSpacing (number): Spacing before/after paragraphs
    - lineSpacing (number): Line spacing multiplier
  - Alignment:
    - paragraphAlignment (string): "LEFT" | "RIGHT" | "CENTER" | "JUSTIFIED"
    - headingAlignment (string): "LEFT" | "RIGHT" | "CENTER" | "JUSTIFIED" (fallback for all headings)
    - heading1Alignment through heading5Alignment (string): Individual heading level alignments
    - blockquoteAlignment (string): "LEFT" | "RIGHT" | "CENTER" | "JUSTIFIED"

Returns

Promise that resolves to a Blob containing the DOCX file.

`downloadDocx(blob: Blob, filename?: string): void`

Downloads a DOCX file in the browser environment.

Parameters

blob (Blob): The Blob containing the DOCX file data
filename (string, optional): The name to save the file as (defaults to "document.docx")

Throws

Error if called outside browser environment
Error if invalid blob or filename is provided
Error if file save fails

Markdown Support

The module supports the following Markdown features:

Table of Contents: [TOC] (place on its own line where TOC should appear)
Page Breaks: \pagebreak (place on its own line to force a page break)
Headings: #, ##, ###, ####, #####
Lists: -, *, 1., 2., etc.
Bold: **text**
Italic: *text*
Strikethrough: ~~text~~
Blockquotes: > text
Tables: | Header | Header |
Comments: COMMENT: text
Images: ![alt text](image-url)
Code blocks: code
Inline code: code
Links: [text](url)
Markdown Separators: --- (horizontal rule, skipped during conversion)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

List Formatting Examples

The module supports rich text formatting within list items:

const markdown = `
- Regular list item
- List item with **bold text** inside
- Item with *italic* and \`code\`
- Mixed **bold** and *italic* formatting
- List item
  **Bold text on next line**

1. Numbered list with **bold text**
2. Numbered item with \`code\` and *italic*
3. Mixed **bold** and *italic* text
`;

const blob = await convertMarkdownToDocx(markdown);

Basic Usage with TOC and Page Breaks

import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const markdown = `
[TOC]

# Section 1

This is the first section.

## Subsection 1.1

Content for subsection 1.1.

\pagebreak

# Section 2

This is the second section, appearing after a page break.

- Item A
- Item B
`;

// Convert to DOCX
const blob = await convertMarkdownToDocx(markdown);

// Download in browser
downloadDocx(blob, "output_with_toc.docx");

markdown docx word converter typescript

8 months ago

9 months ago

9 months ago

9 months ago

10 months ago