md2word 0.1.0

Convert Markdown files to Word documents with extensive customization

md2word

中文文档 | English

Convert Markdown files to Word documents (.docx) with extensive customization options.

Features

• Convert Markdown to Word documents
• Support for tables, code blocks, images, and more
• Automatic download and embedding of web images
• Automatic conversion of unsupported image formats (e.g., WebP)
• LaTeX formula support (converted to native Word equations)
• Configurable styles for headings, body text, and other elements
• Chinese font size support (e.g., "四号", "小四")
• Automatic heading numbering with multiple formats
• Optional table of contents generation

Installation

Using uv (recommended)

# Install globally
uv tool install md2word

# Or run directly without installation
uvx md2word input.md

Using pip

pip install md2word

Usage

Command Line

# Basic conversion (outputs input.docx)
md2word input.md

# Specify output file
md2word input.md -o output.docx

# Use custom config file
md2word input.md -c my_config.json

# Add table of contents
md2word input.md --toc

# Custom TOC title and level
md2word input.md --toc --toc-title "Contents" --toc-level 4

# Generate default config file
md2word --init-config

As a Python Library

import md2word

# Simple conversion
md2word.convert_file("input.md", "output.docx")

# With custom configuration
config = md2word.Config.from_file("config.json")
md2word.convert_file("input.md", "output.docx", config=config, toc=True)

# Convert from string
markdown_content = "# Hello World\n\nThis is a test."
md2word.convert(markdown_content, "output.docx")

# Programmatic configuration
config = md2word.Config()
config.default_font = "Arial"
config.styles["heading_1"] = md2word.StyleConfig(
    font_name="Arial",
    font_size=24,
    bold=True,
    alignment="center",
    numbering_format="chapter",
)
md2word.convert_file("input.md", "output.docx", config=config)

Configuration

Create a config.json file to customize document styles.

Example Configuration

{
    "document": {
        "default_font": "Arial",
        "max_image_width_inches": 6.0
    },
    "styles": {
        "heading_1": {
            "font_name": "Arial",
            "font_size": 24,
            "bold": true,
            "alignment": "center",
            "line_spacing_rule": "exact",
            "line_spacing_value": 28,
            "numbering_format": "chapter"
        },
        "body": {
            "font_name": "Times New Roman",
            "font_size": 12,
            "alignment": "justify",
            "line_spacing_rule": "multiple",
            "line_spacing_value": 1.5,
            "first_line_indent": 2
        }
    }
}

Style Properties

Property	Type	Description
font_name	string	Font name
font_size	number/string	Font size (points or Chinese size name)
bold	boolean	Bold text
italic	boolean	Italic text
color	string	Font color (hex, e.g., "000000")
alignment	string	Paragraph alignment: left/center/right/justify
line_spacing_rule	string	Line spacing mode (see below)
line_spacing_value	number	Line spacing value
first_line_indent	number	First line indent (in characters)
left_indent	float	Left indent (in inches)
space_before	number	Space before paragraph (points)
space_after	number	Space after paragraph (points)
numbering_format	string	Heading numbering format (see below)

Line Spacing Modes

Value	Description
single	Single line spacing
1.5	1.5 line spacing
double	Double line spacing
multiple	Multiple line spacing (use line_spacing_value as multiplier)
exact	Exact line spacing (use line_spacing_value in points)
at_least	Minimum line spacing (use line_spacing_value in points)

Numbering Formats

Format	Example
chapter	第一章, 第二章, 第三章...
section	第一节, 第二节, 第三节...
chinese	一、二、三...
chinese_paren	（一）（二）（三）...
arabic	1. 2. 3...
arabic_paren	(1) (2) (3)...
arabic_bracket	[1] [2] [3]...
roman	I. II. III...
roman_lower	i. ii. iii...
letter	A. B. C...
letter_lower	a. b. c...
circle	① ② ③...
none	No numbering

Custom format strings are also supported using {n} for Arabic numbers and {cn} for Chinese numbers.

Table Configuration

Configure table appearance in the table section:

{
    "table": {
        "border_style": "single",
        "border_color": "000000",
        "border_width": 4,
        "header_background_color": "D9E2F3",
        "cell_background_color": null,
        "alternating_row_color": "F2F2F2",
        "cell_padding_top": 2,
        "cell_padding_bottom": 2,
        "cell_padding_left": 5,
        "cell_padding_right": 5,
        "width_mode": "full",
        "width_inches": null
    }
}

Property	Type	Description
border_style	string	Border style: single/double/dotted/dashed/none
border_color	string	Border color (hex, e.g., "000000")
border_width	number	Border width in 1/8 points (4 = 0.5pt, 8 = 1pt)
header_background_color	string	Header row background color (hex)
cell_background_color	string	Cell background color (hex)
alternating_row_color	string	Alternating row color for zebra striping (hex)
cell_padding_*	number	Cell padding in points (top/bottom/left/right)
width_mode	string	Table width mode: auto/full/fixed
width_inches	number	Fixed width in inches (when width_mode is "fixed")

Chinese Font Sizes

Name	Points	Name	Points
初号	42	小初	36
一号	26	小一	24
二号	22	小二	18
三号	16	小三	15
四号	14	小四	12
五号	10.5	小五	9
六号	7.5	小六	6.5
七号	5.5	八号	5

Requirements

• Python >= 3.10
• markdown2
• python-docx
• html-for-docx
• httpx
• Pillow
• latex2mathml
• mathml2omml
• lxml

License

MIT