---
name: "MD to Word Converter"
client: Oliver Internal
status: active
tech: [Python, python-docx, markdown, BeautifulSoup4, Pillow]
local_path: "/Users/ai_leed/Documents/Projects/Oliver/md to word"
deploy: pip install
url: 
tags: [oliver, markdown, word, converter, utility]
created: 2026-04-14
server: local
---

## Overview
md-to-word is a Python CLI tool that converts Markdown documents to Word (.docx) format with support for Mermaid chart rendering. It parses Markdown syntax, converts it to structured Word document elements, and embeds rendered Mermaid diagrams as images. This is useful for teams that author content in Markdown but need to distribute or collaborate in Microsoft Word format while preserving rich formatting and diagrams.

## Tech Stack
- **Frontend:** N/A (CLI tool)
- **Backend:** Python 3.9+
- **Database:** N/A
- **Infrastructure:** Local/Command-line
- **AI/ML:** N/A
- **Key libraries:** 
  - `python-docx` — Word document generation
  - `markdown` — Markdown parsing
  - `beautifulsoup4` — HTML parsing (intermediate format)
  - `Pillow` — Image processing for diagram rendering

## Architecture
The converter works as a single-pipeline tool:

```
Markdown file (.md)
       ↓
  Markdown parser
       ↓
  HTML intermediate
       ↓
  BeautifulSoup parsing
       ↓
  Mermaid diagram detection & rendering
       ↓
  python-docx document builder
       ↓
  Word file (.docx)
```

**Design flow:**
1. Read Markdown source file
2. Parse Markdown to HTML using the `markdown` library
3. Parse HTML with BeautifulSoup to extract structure and content
4. Detect Mermaid code blocks and render them to PNG images via Mermaid CLI (or similar)
5. Build a Word document programmatically using `python-docx`
6. Insert rendered diagrams as images at appropriate locations
7. Write final .docx file

## Dev Commands
```bash
# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run conversion (after installation)
convert input.md output.docx

# Run directly from module
python -m md_to_word_converter input.md output.docx
```

## Deployment
- **Server:** local
- **Deploy:** `pip install .` or `pip install -e .` for development
- **URL:** N/A
- **Port:** N/A
- **Service:** N/A
- **Local path:** /Users/ai_leed/Documents/Projects/Oliver/md to word

The tool is distributed as a Python package via the `convert` command-line entry point defined in `pyproject.toml`.

## Environment Variables
No environment variables are documented. Configuration is handled via command-line arguments to the `convert` command.

## Known Issues
- Mermaid rendering method not explicitly defined in source files (assumes external tool availability or wrapper library)
- No error handling documentation provided
- Image embedding strategy and quality settings not documented

## Git
- **Remote:** [Not provided in source files]

## Sessions
### 2026-04-14 – Project catalogued
**Done:** Added to Obsidian second brain.

---
## Change Log
| Date | Requested | Changed | Files |
|------|-----------|---------|-------|
| 2026-04-14 | Initial setup | Note created | — |