# How the Invention Disclosure Builder Incorporates Mermaid Flowcharts into Word Documents

> Learn how the invention disclosure builder embeds Mermaid flowcharts into Word docs. Discover the two-step process of rendering diagrams and parsing comments for seamless integration.

- Repository: [handsomestWei/patent-disclosure-skill](https://github.com/handsomestWei/patent-disclosure-skill)
- Tags: how-to-guide
- Published: 2026-09-02

---

**The invention disclosure builder converts Mermaid flowcharts in Markdown to embedded PNG images in Word documents through a two-step pipeline: first rendering diagrams to PNG via Playwright with hidden HTML comments as markers, then parsing those comments during Markdown-to-Word conversion to embed the images.**

The **handsomestWei/patent-disclosure-skill** repository provides a specialized toolchain for generating patent invention disclosures from Markdown source files. A key capability is the seamless integration of **Mermaid** flowcharts—textual diagram definitions—into final Microsoft Word (`.docx`) outputs. This article explains the exact mechanism, tracing the code path from [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) through [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py).

## The Two-Step Rendering Architecture

The builder separates concerns into distinct phases: **diagram generation** and **document assembly**. This design keeps the Markdown source human-readable while ensuring polished visual output in Word.

### Step 1: Render Mermaid Blocks to PNG Images

The [`tools/shared/mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/tools/shared/mermaid_render.py) module handles the heavy lifting of converting Mermaid syntax into raster images. It operates on a draft Markdown file and produces an enriched version ready for Word conversion.

#### Detecting Mermaid Fences

The script scans input Markdown for fenced code blocks beginning with ` ```mermaid`. The rendering logic lives in the `render_one` function (approximately lines 32–48), which orchestrates the browser-based conversion.

#### Headless Browser Rendering with Playwright

Mermaid diagrams require a JavaScript execution environment. The `_PlaywrightMermaid` context manager (lines 82–110) encapsulates this:

```python
from tools.shared.mermaid_render import render_markdown_mermaid

# Process draft.md, writing PNGs and enriched Markdown

render_markdown_mermaid(
    input_path="draft.md",
    output_path="disclosure.md",
    image_dir="./images"
)

```

Inside the browser, the script:

1. Loads a staging HTML template (`_STAGE_HTML`) with an empty `#stage` element
2. Injects the vendored `mermaid.min.js` library
3. Executes `_RENDER_JS` (lines 60–74), which calls `mermaid.render()` to generate SVG
4. Captures a screenshot via `page.locator("#stage").screenshot()` (line 47)

The PNG output is written to a configurable directory, typically `./images/mermaid-{n}.png`.

#### Inserting Hidden HTML Comments

Crucially, the original Mermaid fence **remains intact** in the Markdown. After each fenced block, the renderer appends a hidden HTML comment that serves as a metadata marker:

```markdown

```mermaid
graph TB
    A[Invention Concept] --> B{Novel?}
    B -->|Yes| C[Proceed to Claims]
    B -->|No| D[Document Prior Art]

```

<!-- ![图示](./images/mermaid-1.png) -->

```

The comment format is governed by `_MERMAID_HIDDEN_COMMENT_RE` (lines 52–54), which matches the pattern `<!-- ![alt](path) -->`. This convention enables lossless round-tripping: the Markdown stays readable, while downstream processors can locate and embed the corresponding images.

### Step 2: Convert Enriched Markdown to Word

The `tools/shared/md_to_docx.py` module completes the pipeline by transforming the enriched Markdown into a `.docx` file, handling the hidden comment markers to embed PNGs.

#### Parsing Hidden Image Comments

The converter uses `_HIDDEN_MD_IMAGE_COMMENT_RE` (lines 57–58) to detect the special HTML comments inserted in step 1. The helper function `_parse_hidden_image_comment()` (lines 93–100) extracts:

- **Alt text**: The description inside `![...]` (e.g., "图示" meaning "illustration")
- **Image path**: The relative path inside `(...)`

#### Embedding Images with python-docx

Once extracted, the PNG is embedded into the Word document using `python-docx` primitives. The `_embed_from_image_ref` helper and related functions manage:

- Loading the image file from the extracted path
- Sizing and positioning within the document flow
- Maintaining the association between the Mermaid code block (preserved as literal text) and its visual representation

### Complete Pipeline Execution

The full workflow from draft to final document:

```bash

# Step 1: Generate PNGs and enriched Markdown

python tools/shared/mermaid_render.py \
    --input draft.md \
    --output disclosure.md \
    --image-dir ./images

# Step 2: Produce Word document with embedded diagrams

python tools/shared/md_to_docx.py \
    --input disclosure.md \
    --output disclosure.docx

```

After execution, `disclosure.docx` contains both the original Mermaid source (for archival/review purposes) and the rendered flowchart image positioned at the corresponding location.

## Shared Infrastructure: Browser Management

Both steps rely on [`tools/shared/browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/tools/shared/browser.py), which provides vendor-agnostic Chromium launching via Playwright. Key utilities include:

- `launch_chromium()`: Configures headless browser instance
- `playwright_installed()`: Verifies environment readiness

This centralization ensures consistent browser behavior across rendering and testing workflows.

## Testing the Integration

The repository includes [`tests/shared/test_mermaid_browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/tests/shared/test_mermaid_browser.py), which validates end-to-end Mermaid rendering. This test confirms that:

- Mermaid fences are correctly identified
- PNG files are generated with valid image data
- Hidden comments follow the expected format

Running these tests ensures the two-step pipeline remains functional across environment changes.

## Configuration and Customization

Several parameters control the rendering behavior:

| Parameter | Location | Effect |
|-----------|----------|--------|
| `--image-dir` / `image_dir` | [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) CLI | Output directory for PNG files |
| `--mermaid-theme` | Mermaid config | Visual styling of diagrams (default, dark, forest, neutral) |
| Browser timeout | `_PlaywrightMermaid` | Maximum wait for diagram rendering |

Advanced users can modify `_STAGE_HTML` or `_RENDER_JS` in [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) to inject custom CSS or Mermaid configuration options.

## Summary

- **Separation of concerns**: Diagram rendering ([`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py)) and document assembly ([`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py)) are distinct, composable steps
- **Hidden HTML comments**: Serve as lossless metadata markers linking Mermaid source blocks to their PNG renderings
- **Playwright-based rendering**: Provides accurate, browser-consistent diagram generation without external dependencies like Node.js CLI tools
- **Preserved source**: Original Mermaid fences remain in the Word document, enabling future editing and audit trails

## Frequently Asked Questions

### How does the builder handle Mermaid syntax errors?

[`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) delegates error handling to the Mermaid.js library running in Playwright. If `mermaid.render()` fails, the JavaScript exception propagates through the browser context, causing `render_one` to raise a runtime error. The original Markdown fence is not modified, so the user can correct the syntax and re-run.

### Can I customize the image format or resolution?

Currently, [`browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/browser.py) and [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) generate PNG via Playwright's screenshot API. The resolution is determined by the browser viewport size configured in `_STAGE_HTML`. To change formats (e.g., SVG embedding), you would need to modify `render_one` to capture SVG source directly and adjust [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py) to handle vector image embedding.

### Why use hidden HTML comments instead of standard Markdown image syntax?

Standard Markdown images (`![alt](path)`) would render visibly in HTML previews and confuse the document structure. Hidden HTML comments are invisible in rendered output but parseable by [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py). This preserves a clean reading experience while enabling the Word converter to locate and substitute the correct visual assets.

### Is Playwright required for all users of the disclosure builder?

Yes, Playwright and its Chromium browser are required dependencies for [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py). The [`browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/browser.py) module provides `playwright_installed()` to verify the environment. Users without Playwright can still run [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py) on pre-rendered Markdown files containing the hidden comment markers.