The Role of Mermaid in Generating Patent Diagrams

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 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.

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

```

Headless Browser Rendering Pipeline

The 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 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 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) 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.

After PNG generation, mermaid_render.py leaves HTML comments that reference the image assets. The subsequent 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 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:

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:

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 – Validates that ensure_step_ids_in_visible_labels correctly injects step identifiers into node labels.
• 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.
• 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}