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

1npm install @mohtasham/md-to-docx

Usage

Basic Usage

1import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";
2
3const markdown = `
4# Title
5## Subtitle
6This is a paragraph with **bold** and *italic* text.
7
8- Bullet point with **bold text** inside
9- Another point with *italic* and \`code\`
10  **Bold text on next line**
11
121. Numbered item with **bold** formatting
132. Another item with mixed **bold** and *italic*
14
15> This is a blockquote
16
17| Header 1 | Header 2 |
18|----------|----------|
19| Cell 1   | Cell 2   |
20| Cell 3   | Cell 4   |
21
22\`\`\`typescript
23function hello(name: string): string {
24  return \`Hello, \${name}!\`;
25}
26\`\`\`
27
28![Test Image](https://picsum.photos/200/200)
29
30COMMENT: This is a comment
31`;
32
33// Convert to DOCX
34const blob = await convertMarkdownToDocx(markdown);
35
36// Download in browser
37downloadDocx(blob, "output.docx");

With Custom Options

1const options = {
2  documentType: "report", // or 'document'
3  style: {
4    titleSize: 32,
5    headingSpacing: 240,
6    paragraphSpacing: 240,
7    lineSpacing: 1.15,
8    heading1Size: 32,
9    heading2Size: 28,
10    heading3Size: 24,
11    heading4Size: 20,
12    heading5Size: 18,
13    paragraphSize: 24,
14    listItemSize: 24,
15    codeBlockSize: 20,
16    blockquoteSize: 24,
17    tocFontSize: 22, // Custom font size for TOC entries
18    paragraphAlignment: "JUSTIFIED",
19    blockquoteAlignment: "CENTER",
20  },
21};
22
23const blob = await convertMarkdownToDocx(markdown, options);

Custom Table of Contents Styling

1const options = {
2  documentType: "document",
3  style: {
4    // Regular document styling
5    titleSize: 32,
6    headingSpacing: 240,
7    paragraphSpacing: 240,
8
9    // Custom TOC styling for each heading level
10    tocHeading1FontSize: 28,
11    tocHeading1Bold: true,
12    tocHeading1Italic: false,
13
14    tocHeading2FontSize: 24,
15    tocHeading2Bold: true,
16    tocHeading2Italic: false,
17
18    tocHeading3FontSize: 22,
19    tocHeading3Bold: false,
20    tocHeading3Italic: false,
21
22    tocHeading4FontSize: 20,
23    tocHeading4Bold: false,
24    tocHeading4Italic: true,
25
26    tocHeading5FontSize: 18,
27    tocHeading5Bold: false,
28    tocHeading5Italic: true,
29  },
30};
31
32const blob = await convertMarkdownToDocx(markdownWithToc, options);

Text Alignment Example

1const markdownWithAlignment = `
2# Left-Aligned Heading 1
3
4## Left-Aligned Heading 2
5
6This 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.
7
8> This is a centered blockquote that stands out from the regular text.
9
10This is a left-aligned paragraph (default alignment) that shows the standard text positioning.
11`;
12
13const alignmentOptions = {
14  documentType: "document",
15  style: {
16    paragraphAlignment: "JUSTIFIED",
17    blockquoteAlignment: "CENTER",
18    // All headings default to LEFT alignment
19  },
20};
21
22const blob = await convertMarkdownToDocx(
23  markdownWithAlignment,
24  alignmentOptions
25);

Custom Heading Alignments

You can customize the alignment for each heading level individually:

1const customHeadingOptions = {
2  documentType: "document",
3  style: {
4    // Individual heading alignments
5    heading1Alignment: "CENTER", // H1 will be centered
6    heading2Alignment: "RIGHT", // H2 will be right-aligned
7    heading3Alignment: "JUSTIFIED", // H3 will be justified
8    heading4Alignment: "LEFT", // H4 will be left-aligned
9    heading5Alignment: "CENTER", // H5 will be centered
10
11    // Other style options
12    paragraphAlignment: "LEFT", // Paragraphs will be left-aligned
13    blockquoteAlignment: "LEFT", // Blockquotes will be left-aligned
14  },
15};
16
17const markdown = `
18# This will be centered
19## This will be right-aligned
20### This will be justified
21#### This will be left-aligned
22##### This will be centered
23`;
24
25const blob = await convertMarkdownToDocx(markdown, customHeadingOptions);

In React

1import { useState } from "react";
2import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";
3
4function MarkdownConverter() {
5  const [markdown, setMarkdown] = useState("");
6
7  const handleConvert = async () => {
8    try {
9      const blob = await convertMarkdownToDocx(markdown);
10      downloadDocx(blob, "converted.docx");
11    } catch (error) {
12      console.error("Conversion failed:", error);
13    }
14  };
15
16  return (
17    <div>
18      <textarea
19        value={markdown}
20        onChange={(e) => setMarkdown(e.target.value)}
21      />
22      <button onClick={handleConvert}>Convert to DOCX</button>
23    </div>
24  );
25}

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:

1const markdown = `
2- Regular list item
3- List item with **bold text** inside
4- Item with *italic* and \`code\`
5- Mixed **bold** and *italic* formatting
6- List item
7  **Bold text on next line**
8
91. Numbered list with **bold text**
102. Numbered item with \`code\` and *italic*
113. Mixed **bold** and *italic* text
12`;
13
14const blob = await convertMarkdownToDocx(markdown);

Basic Usage with TOC and Page Breaks

1import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";
2
3const markdown = `
4[TOC]
5
6# Section 1
7
8This is the first section.
9
10## Subsection 1.1
11
12Content for subsection 1.1.
13
14\pagebreak
15
16# Section 2
17
18This is the second section, appearing after a page break.
19
20- Item A
21- Item B
22`;
23
24// Convert to DOCX
25const blob = await convertMarkdownToDocx(markdown);
26
27// Download in browser
28downloadDocx(blob, "output_with_toc.docx");