# How patent-disclosure-skill Handles Mermaid Diagrams for Invention Patents

> Learn how patent-disclosure-skill integrates Mermaid diagrams as optional visual aids for invention patents by rendering claim-tree JSON to PNG with Playwright for enhanced clarity.

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

---

**The patent-disclosure-skill treats Mermaid diagrams as optional visual supplements that are generated from claim-tree JSON, rendered to PNG via Playwright, and conditionally embedded to avoid duplication with tabular claim structures.**

The handsomestWei/patent-disclosure-skill repository implements a three-stage pipeline for managing **Mermaid diagrams** within patent disclosure documents. This system converts logical claim structures into visual flowcharts while maintaining clean separation between source code, rendered images, and final document output.

## Three-Stage Mermaid Pipeline in patent-disclosure-skill

The handling of Mermaid diagrams consists of three tightly-coupled stages: generation from claim trees, headless browser rendering, and conditional inclusion based on output format.

### Stage 1: Generating Mermaid Scripts from Claim Trees

The process begins in **[`skills/patent-reader/tools/vault/obsidian.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-reader/tools/vault/obsidian.py)**, where the function **`claim_tree_to_mermaid`** (lines 199‑300) converts a [`claim_tree.json`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/claim_tree.json) file into a Mermaid script. This function treats each independent claim as a sub‑graph, building a hierarchical visual representation of the patent's logical structure.

The generated script describes the relationships between claims using Mermaid's graph syntax, creating a machine‑readable visualization that mirrors the tabular claim structure. By default, this output is stored as a separate `.mmd` file or embedded as a fenced code block within the markdown draft.

### Stage 2: Rendering PNG Images with Playwright

Once the markdown contains fenced `mermaid` blocks, the CLI tool **[`skills/patent-disclosure/tools/mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tools/mermaid_render.py)** handles the rendering pipeline (lines 262‑320). The script scans the document for triple-backtick `mermaid` sections and launches a headless Playwright browser instance.

The browser loads the bundled **[`vendor/mermaid.min.js`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/vendor/mermaid.min.js)** (version 11.4.1) to render diagrams without external network dependencies. For each block, the tool generates a PNG image saved adjacent to the source file, then appends an HTML comment `<!-- ![图示](relative/path.png) -->` pointing to the image. This comment serves as a marker for downstream DOCX conversion while preserving the original Mermaid source for debugging.

### Stage 3: Conditional Inclusion Policy

The final stage enforces a strict **"no duplicate visualisation"** rule implemented in **[`skills/patent-reader/tools/vault/write_patent_obsidian_note.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-reader/tools/vault/write_patent_obsidian_note.py)** (lines 998‑1002). By default, the generated Mermaid diagram is excluded from the markdown body to prevent redundancy with the tabular "结构图" section.

When users require visual output, they must explicitly enable inclusion via the `--docx` CLI flag or by setting **`include_mermaid=True`** in the Python API. The script inserts the header `### 结构图（可选 mermaid）` (line 107) only when this flag is active, ensuring the fenced block appears in the final output exactly once and only when requested.

## Implementation Details and Source Files

The Mermaid pipeline relies on specific source files that handle distinct responsibilities:

- **[`skills/patent-reader/tools/vault/obsidian.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-reader/tools/vault/obsidian.py)** – Contains the core `claim_tree_to_mermaid` function that transforms JSON claim trees into Mermaid graph definitions.
- **[`skills/patent-disclosure/tools/mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-disclosure/tools/mermaid_render.py)** – CLI utility that finds fenced Mermaid blocks, executes Playwright rendering, and manages PNG output with HTML comment markers.
- **[`skills/patent-reader/tools/vault/write_patent_obsidian_note.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-reader/tools/vault/write_patent_obsidian_note.py)** – Controls conditional embedding through the `include_mermaid` parameter and manages the "结构图（可选 mermaid）" section headers.
- **[`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)** – Bundled Mermaid library (v 11.4.1) enabling offline rendering without external CDN dependencies.

## Code Examples

Generate a claim-tree Mermaid file from JSON:

```bash
python tools/analyze/build_claim_mermaid.py \
    --claim-tree claim_tree.json \
    --pub-number CN1234567 \
    -o claim_mermaid.mmd

```

Render all Mermaid blocks in a draft to PNG while preserving source:

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

```

Optionally embed Mermaid when generating final markdown via Python API:

```python
from tools.vault.obsidian import claim_tree_to_mermaid

md = render_claim_tree_markdown(
    claim_tree,
    pub="CN1234567",
    include_mermaid=True   # Forces insertion of the fenced block

)

```

## Summary

- The **patent-disclosure-skill** generates Mermaid diagrams from claim-tree JSON using `claim_tree_to_mermaid` in [`obsidian.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/obsidian.py).
- **Playwright** and bundled **mermaid.min.js** (v 11.4.1) render diagrams to PNG via [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py).
- HTML comments link rendered images for DOCX conversion while preserving source code blocks.
- The **conditional inclusion policy** prevents duplicate visualization by default, requiring explicit `include_mermaid=True` or `--docx` flags to embed diagrams.
- Source files in `skills/patent-reader/` and `skills/patent-disclosure/` manage generation, rendering, and policy enforcement respectively.

## Frequently Asked Questions

### How does patent-disclosure-skill convert patent claims into Mermaid diagrams?

The conversion happens in [`skills/patent-reader/tools/vault/obsidian.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-reader/tools/vault/obsidian.py) through the `claim_tree_to_mermaid` function (lines 199‑300). This function parses the [`claim_tree.json`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/claim_tree.json) structure and maps each independent claim to a Mermaid sub‑graph, outputting a fenced code block that represents the hierarchical claim relationships visually.

### Why does the skill use Playwright instead of native Mermaid CLI for rendering?

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 uses a headless Playwright browser loading the bundled [`vendor/mermaid.min.js`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/vendor/mermaid.min.js) (v 11.4.1) to ensure consistent rendering without external network dependencies. This approach guarantees that the specific Mermaid version produces identical PNG outputs across different environments while allowing the tool to inject HTML comments for downstream DOCX processing.

### When are Mermaid diagrams actually embedded in the final patent disclosure?

By default, diagrams are excluded to avoid duplication with tabular claim structures. They appear only when users explicitly request DOCX output via the `--docx` flag or set `include_mermaid=True` in the Python API, as implemented in [`write_patent_obsidian_note.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/write_patent_obsidian_note.py) (lines 998‑1002). The script then inserts the `### 结构图（可选 mermaid）` header and embeds the fenced block.

### Can I manually edit the Mermaid source after generation?

Yes. The pipeline preserves the original Mermaid source code in the markdown file even after PNG rendering. The [`mermaid_render.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/mermaid_render.py) tool keeps the fenced code blocks intact and appends HTML comments referencing the generated images, allowing manual debugging, editing, or regeneration of diagrams without losing upstream modifications.