---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: User_Manual
status: active
tags:
- domain/devops
- tech/markdown
- tech/mermaid
- tech/python
- type/sop
type: sop
---

# MD to Word Converter User Manual

## What This Tool Does

This tool converts Markdown (`*.md`) documents into Microsoft Word (`*.docx`) documents. It features:

- **Rich formatting preservation**: Headers, lists, bold/italic text, tables, etc., are preserved in the Word output.
- **Mermaid chart rendering**: Inline Mermaid code blocks are extracted, rendered to images, and embedded into the Word document.
- **Custom styling**: Uses Montserrat font and a #FFC407 accent color palette for Mermaid charts and node styling.

## Who Uses It

- Technical writers who need to produce professionally formatted Word documents from Markdown source.
- Developers and analysts who use Mermaid diagrams in their documentation and need them rendered in final deliverables.
- Teams that standardize on Markdown for authoring and Word for distribution or editing by non-technical stakeholders.

## How to Access

### Prerequisites

- Python 3.9 or higher
- pip package manager

### Installation

1. Clone or download the project.
2. Install dependencies:
   ```bash
   pip install python-docx markdown beautifulsoup4 pillow
   ```

### Running the Tool

The tool provides a command-line interface via the `convert` script.

```bash
convert <input_markdown_file> <output_word_file>
```

Example:
```bash
convert README.md output.docx
```

## Main Workflows

### 1. Basic Conversion

1. Prepare your Markdown file with standard Markdown syntax.
2. If you have Mermaid diagrams, enclose them in ` ```mermaid ` blocks.
3. Run the conversion command as shown above.
4. Open the resulting `.docx` file in Microsoft Word or compatible editor.

### 2. Converting with Mermaid Diagrams

1. Write your Mermaid diagram inside a code block:
   ```markdown
   ```mermaid
   graph TD
       A[Start] --> B{Decision}
       B -->|Yes| C[End]
       B -->|No| D[Process]
   ```
   ```
2. The converter will:
   - Extract the Mermaid code.
   - Render it to an image using an internal Mermaid rendering process (which requires Mermaid CLI to be installed separately on your system, if applicable).
   - Embed the image into the Word document.
3. Run the conversion command.
4. Verify that diagrams appear correctly in the output.

### 3. Troubleshooting Common Issues

- **Mermaid diagrams not appearing**: Ensure you have Mermaid CLI (`@mermaid-js/mermaid-cli`) installed globally via npm: `npm install -g @mermaid-js/mermaid-cli`. Also check that the system has a compatible headless browser (e.g., Puppeteer/Playwright).
- **Font display issues**: The tool specifies Montserrat font in Mermaid CSS. Ensure the target system has access to Montserrat (loaded via Google Fonts) or substitute locally if needed.
- **Missing dependencies**: If you see `ImportError`, reinstall dependencies: `pip install -r requirements.txt` or install individually.

## FAQ

**Q: Does it support all Markdown features?**
A: It supports standard Markdown elements via the `markdown` library and additional formatting via `python-docx`. Complex HTML or custom extensions may not be fully supported.

**Q: Can I customize the output styles?**
A: Currently, custom styles are limited to Mermaid chart CSS. Global document styles are not yet configurable via UI/CLI.

**Q: Is the tool free and open source?**
A: Yes, the tool is open source and available under its project license.

**Q: Can I convert multiple files at once?**
A: The current CLI supports one input file per run. Use shell loops or scripts to batch convert.

**Q: What happens if a Mermaid diagram has syntax errors?**
A: The renderer may fail silently or produce broken images. Check your Mermaid syntax carefully before conversion.

## Related
- [[01 Projects/md to word/DEVELOPER_MANUAL]]
- [[01 Projects/md to word/DEVELOPER_MANUAL.md]]
- [[Mermaid CLI Installation]]