# The Role of Mermaid in Generating Patent Diagrams

> Discover how Mermaid generates high-resolution patent diagrams from simple text descriptions. Learn to create professional visuals for your patent disclosures efficiently.

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

---

**Mermaid functions as the core rendering engine that transforms textual diagram descriptions into high-resolution PNG images embedded within patent disclosure documents.**

The `handsomestWei/patent-disclosure-skill` repository utilizes Mermaid to automate the creation of technical diagrams for patent applications. This integration allows patent authors to define flowcharts and system block diagrams using declarative text syntax, which the toolchain converts into publication-ready figures suitable for Word document submission.

## Core Architecture of Mermaid Integration

Patent writers embed diagrams using standard fenced code blocks marked with `mermaid`. The [`skills/patent-disclosure/tools/mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tools/mermaid_render.py) script processes these blocks to generate visual assets.

### Declarative Diagram Authoring

Authors insert Mermaid syntax directly into draft Markdown files. This approach keeps diagrams version-controlled and readable alongside technical text.

````markdown

```mermaid
flowchart LR
    A[收集数据] --> B[处理数据]
    B --> C{是否合格？}
    C -->|是| D[生成报告]
    C -->|否| E[重新收集]

```

````

### Headless Browser Rendering Pipeline

The [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) script launches a headless Chromium instance via Playwright to render diagrams. It injects the bundled Mermaid library located at [`skills/patent-disclosure/tools/vendor/mermaid.min.js`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tools/vendor/mermaid.min.js) and executes the internal `_RENDER_JS` code block to convert text descriptions into SVG format, subsequently saving them as PNG files.

## The Rendering Process from Syntax to Image

The transformation from text to image involves several precise steps handled by the `render_markdown_mermaid` function.

### From Mermaid Syntax to SVG and PNG

When processing a Markdown file, the script:

1. Parses fenced Mermaid blocks using regex patterns.
2. Launches a Playwright browser context.
3. Injects the [`mermaid.min.js`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid.min.js) vendor library.
4. Executes the rendering JavaScript to generate SVG.
5. Converts SVG to high-resolution PNG saved in `mermaid_figures/`.

The script stores output using a numbered sequence (e.g., `fig_001.png`) and inserts HTML comments into the Markdown: `<!-- ![图示 1](mermaid_figures/fig_001.png) -->`.

### Ensuring Step-ID Visibility

For patent clarity, the `ensure_step_ids_in_visible_labels` helper function (defined in [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py)) rewrites node labels to ensure step identifiers like `S1` or `S2` remain visible in the rendered output. This guarantees that process flow references in the patent text match the visual diagram exactly.

## Integration with Word Document Output

The generated PNGs flow into final Word documents through a coordinated pipeline involving [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py).

After PNG generation, [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) leaves HTML comments that reference the image assets. The subsequent [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py) step reads these specific comment markers and embeds the corresponding PNG files into the Word document. Notably, the original Mermaid source code is omitted from the final Word output, ensuring only the professional-rendered diagrams appear in the disclosure package.

## Error Handling and Graceful Fallbacks

The rendering system implements robust error handling to prevent build failures. If Playwright or Chromium is unavailable, or if rendering fails for any diagram, the [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) script preserves the original Mermaid fenced block unchanged. This allows the Markdown pipeline to continue processing without interruption, enabling authors to fix diagram syntax later while maintaining document flow.

## Using the Rendering Tool

### Command Line Execution

Run the renderer directly from the terminal to process a draft Markdown file:

```bash
python tools/mermaid_render.py -i draft.md -o disclosure.md

# Generates PNGs under ./mermaid_figures and writes disclosure.md with image references

```

### Programmatic API Integration

Import the rendering function directly into Python scripts for custom workflows:

```python
from mermaid_render import render_markdown_mermaid
from pathlib import Path

md_text = Path("draft.md").read_text(encoding="utf-8")
new_md, ok, fail = render_markdown_mermaid(
    md_text,
    out_md_path=Path("disclosure.md"),
    assets_rel="mermaid_figures"
)
print(f"Rendered {ok} diagrams, {fail} failures")

```

### Testing and Validation

The repository includes comprehensive test coverage for the Mermaid pipeline:

- **[`skills/patent-disclosure/tests/test_mermaid_step_labels.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tests/test_mermaid_step_labels.py)** – Validates that `ensure_step_ids_in_visible_labels` correctly injects step identifiers into node labels.
- **[`skills/patent-disclosure/tests/test_mermaid_browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tests/test_mermaid_browser.py)** – Integration tests verifying PNG generation accuracy and proper HTML comment insertion.

## Summary

- **Mermaid provides the declarative syntax** for describing patent diagrams directly in Markdown drafts.
- **The `render_markdown_mermaid` function** orchestrates headless browser rendering via Playwright to convert text to PNG images.
- **Step identifiers remain visible** through the `ensure_step_ids_in_visible_labels` helper, ensuring patent text references align with diagrams.
- **HTML comment markers** bridge the gap between Markdown processing and Word document generation via [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py).
- **Graceful fallback mechanisms** preserve source blocks when rendering infrastructure is unavailable.

## Frequently Asked Questions

### How does the repository handle Mermaid rendering failures?

If the Playwright browser instance fails to start or encounters an error during diagram generation, the [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) script catches the exception and retains the original fenced Mermaid block in the output Markdown. This ensures the document pipeline continues without breaking, allowing authors to address diagram issues separately while preserving the text content.

### What is the purpose of the HTML comments inserted by the renderer?

The script inserts specially formatted HTML comments such as `<!-- ![图示 1](mermaid_figures/fig_001.png) -->` to serve as markers for the [`md_to_docx.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/md_to_docx.py) conversion tool. These comments indicate where to embed PNG images in the final Word document while keeping the raw Mermaid source excluded from the patent disclosure output.

### How does the system ensure step identifiers remain visible in complex flowcharts?

The repository includes a helper function called `ensure_step_ids_in_visible_labels` within [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) that preprocesses the Mermaid source code. This function rewrites node labels to guarantee that step identifiers like `S1`, `S2`, or `S3` appear visibly in the rendered PNG, ensuring the diagram accurately represents the described process flow for patent examiners.

### Can the Mermaid rendering tool be used independently of the full patent disclosure pipeline?

Yes, the [`skills/patent-disclosure/tools/mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tools/mermaid_render.py) script can operate as a standalone utility. You can invoke it programmatically via the `render_markdown_mermaid` function or from the command line using `python tools/mermaid_render.py -i draft.md -o disclosure.md` to generate PNG assets and processed Markdown without triggering the full Word document generation workflow.