---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- domain/devops
- tech/docker
- tech/hatchling
- tech/python
- type/sop
type: sop
---

# MD to Word Converter Developer Manual

## Architecture Overview

The project is a CLI-driven Python application with the following components:

- **`md_to_word_converter.py`**: Main module containing:
  - `MermaidChartHandler`: Class to extract, validate, and render Mermaid charts.
  - `main()` function: CLI entry point that orchestrates the conversion process.
- **`pyproject.toml`**: Project metadata, dependencies, and build configuration using `hatchling`.

## Tech Stack

- **Python**: 3.9+
- **Core Libraries**:
  - `python-docx`: For creating and manipulating Word documents.
  - `markdown`: For parsing Markdown content.
  - `beautifulsoup4`: For parsing HTML fragments if needed.
  - `Pillow`: For image processing (used for Mermaid chart rendering).
- **Build Tool**: `hatchling`

## Local Setup

1. **Clone the repository**:
   ```bash
   git clone <repository-url>
   cd md-to-word
   ```

2. **Create a virtual environment** (recommended):
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -e .
   ```

4. **Verify installation**:
   ```bash
   convert --help
   ```

## Environment Variables

Currently, no environment variables are required. However, if future versions require Mermaid CLI paths or CSS overrides, they may be added.

## Key Services & Entry Points

### `MermaidChartHandler`

- **`__init__`**: Initializes temp directory and creates Mermaid CSS file.
- **`_create_mermaid_css`**: Generates CSS for Mermaid styling with Montserrat font and #FFC407 accents.
- **`extract_mermaid_charts`**: Extracts Mermaid code blocks from Markdown.

### `main()` Entry Point

Located in `md_to_word_converter.py`, this function:

1. Parses CLI arguments.
2. Reads the input Markdown file.
3. Converts Markdown to HTML.
4. Processes Mermaid charts.
5. Builds the Word document using `python-docx`.
6. Saves the output `.docx` file.

## API Reference

### `MermaidChartHandler.extract_mermaid_charts(md_content: str) -> List[Dict]`

Extracts Mermaid charts from Markdown content.

- **Args**:
  - `md_content` (str): Markdown content as a string.
- **Returns**:
  - List of dictionaries with chart info (code, index, etc.).

### `main()`

CLI entry point.

- **Usage**: `convert <input> <output>`
- **Arguments**:
  - `input`: Path to input Markdown file.
  - `output`: Path to output Word file.

## Deployment

### Distributing as a Package

1. Build the package:
   ```bash
   hatch build
   ```
2. Publish to PyPI:
   ```bash
   hatch publish
   ```

### Docker Deployment

A Dockerfile can be created to containerize the application. Ensure system dependencies (e.g., Mermaid CLI, Puppeteer) are installed in the Docker image.

## Known Gotchas

- **Mermaid Rendering Dependency**: The tool relies on an external Mermaid CLI. Ensure it is installed and accessible in the system PATH.
- **Font Loading**: Mermaid CSS loads Montserrat from Google Fonts. In offline environments, provide a local font file or use a different font family.
- **Temporary Files**: The tool creates temp files for Mermaid rendering. These are not cleaned up automatically in all cases.
- **Python Version**: Requires Python 3.9+. Do not use with Python <3.9 due to dependency compatibility.
- **Large Documents**: Performance may degrade with very large Markdown files due to repeated temp file creation and Mermaid rendering.

## Related

- [[01 Projects/md to word/USER_MANUAL]]
- [[01 Projects/md to word/USER_MANUAL.md]]