MD2DOCX

A markdown to DOCX build system using pandoc and Lua filters.

Features

• Groups markdown files by prefix (text before first hyphen)
• Creates separate DOCX files for each group
• Applies Lua filters from both global (~/.config/md2docx/filters) and local directories
• Uses reference DOCX for consistent styling
• Rich terminal output with progress indication
• Global filter support for shared processing rules

Installation

Using uv

# Clone the repository
git clone <your-repo-url>
cd md2docx

# Install with uv
uv tool install -e .

# Optional: Create global filters directory
mkdir -p ~/.config/md2docx/filters

Using pip

# Clone the repository
git clone <your-repo-url>
cd md2docx

# Install with pip
pip install -e .

# Optional: Create global filters directory
mkdir -p ~/.config/md2docx/filters

Setup Global Filters (Optional)

Create a directory for filters that will be used across all projects:

mkdir -p ~/.config/md2docx/filters

# Copy commonly used filters
cp path/to/common-filter.lua ~/.config/md2docx/filters/

Prerequisites

• Python 3.8+
• pandoc (install from https://pandoc.org/installing.html)

Usage

Initialize global configuration (first time only):

md2docx --init

Basic usage:

md2docx --reference "Company Template.docx"

With custom directories:

md2docx \
  --chapters Poglavja/ \
  --reference "reference.docx" \
  --filters Scripts/ \
  --output-dir output/

Disable global filters:

md2docx --reference "reference.docx" --no-global-filters

Options

• --init: Initialize global MD2DOCX configuration
• -c, --chapters: Directory containing markdown files (default: Chapters)
• -r, --reference: Reference DOCX file for styling (required)
• -f, --filters: Directory containing local Lua filters (default: Scripts)
• --no-global-filters: Disable global filters from ~/.config/md2docx/filters
• -o, --output-dir: Output directory for documents (default: current directory)
• -v, --verbose: Show detailed output

Alternative Directory Names

While the default chapters directory is Chapters, you can use any directory name:

# Using 'chapters' directory
md2docx --chapters chapters/ --reference template.docx

# Using 'docs' directory  
md2docx --chapters docs/ --reference template.docx

# Using 'markdown' directory
md2docx --chapters markdown/ --reference template.docx

How It Works

1. File Grouping: The tool scans the chapters directory for markdown files and groups them by their prefix (text before the first hyphen in the filename).

2. Document Generation: For each group, it creates a separate DOCX file named {prefix}.docx.

3. Lua Filters: The tool applies Lua filters from two sources:

   • Global filters: ~/.config/md2docx/filters/ (shared across all projects)
   • Local filters: Directory specified by --filters option
   • All filters are applied in order: global filters first, then local filters

4. Styling: The reference DOCX file is used as a template for consistent styling across all generated documents.

Global Filters

You can place commonly used Lua filters in ~/.config/md2docx/filters/ to have them automatically applied to all documents:

# Create global filters directory
mkdir -p ~/.config/md2docx/filters

# Copy common filters there
cp common-filter.lua ~/.config/md2docx/filters/

These global filters will be combined with any local filters specified via the --filters option.

Example

Given these markdown files in Chapters/:

• Requirements-Database_Design.md
• Requirements-User_Authentication.md
• Testing-User_Authentication.md
• Requirements-Payment_Processing.md

The tool will create:

• Requirements.docx (containing all Requirements-* files)
• Testing.docx (containing all Testing-* files)

Example Output

MD2DOCX - Markdown to DOCX Build System 📚

📄 Reference document: Company Template.docx
📁 Chapters directory: Chapters

🔧 Found 3 Lua filter(s):
  Global filters (~/.config/md2docx/filters/):
    • normalize-tables.lua
    • fix-headers.lua
  Local filters (Scripts/):
    • add-space-after-tables.lua

╭──────────────────────────────────────────────────────────────────────╮
│ Markdown Files Grouped by Prefix                                     │
├──────────────────────────────────────────────────────────────────────┤
│ Prefix              Files                   Output                   │
├──────────────────────────────────────────────────────────────────────┤
│ Requirements        Requirements-Database... Requirements.docx       │
│                     Requirements-User_Au...                          │
│                     Requirements-Payment...                          │
│ Testing             Testing-User_Authent... Testing.docx             │
╰──────────────────────────────────────────────────────────────────────╯

✅ Successfully created: Requirements.docx
✅ Successfully created: Testing.docx

Summary:
  ✅ Successfully created: 2 document(s)

Development

Install development dependencies:

uv pip install -e ".[dev]"

Run tests:

pytest

Format code:

ruff format src/

Lint code:

ruff check src/

Fix linting issues automatically:

ruff check --fix src/