Companion Doc

Create prose documents from markdown, with Mermaid diagrams rendered as images and pandoc conversion to docx.

Prerequisites

pip install --break-system-packages pypandoc_binary  # pandoc wrapper
npm install -g @mermaid-js/mermaid-cli               # mmdc for diagram rendering

Process

1. Write the doc as markdown

Place it wherever makes sense for the project. Use Mermaid for diagrams:

```mermaid
graph LR
    A["User"] --> B["Agent"] --> C["Platform"] --> D["Tool"]
```

2. Render Mermaid blocks to PNG

Extract each mermaid block, render with mmdc:

cat > /tmp/diagram.mmd << 'EOF'
graph LR
    A --> B --> C
EOF
mmdc -i /tmp/diagram.mmd -o diagram.png -b white --scale 2

3. Create docx

Replace mermaid blocks with image refs, then convert:

import re, pypandoc

with open('doc.md') as f:
    content = f.read()

# Replace each mermaid block with its rendered image
content = re.sub(
    r'```mermaid\n(graph|flowchart).*?```',
    '![Diagram](diagram.png)',
    content, count=1, flags=re.DOTALL
)

with open('doc-for-docx.md', 'w') as f:
    f.write(content)

pypandoc.convert_file('doc-for-docx.md', 'docx', outputfile='output.docx')

For multiple diagrams, render each to a separate PNG and replace in sequence.

Writing Guidelines

Framing

Structure

Diagrams