Mermaid Rendering Integration
Relevant source files
The following files were used as context for generating this wiki page:
Mermaid Rendering Integration defines the automated process of extracting, processing, and rendering diagram source code from the project's architectural documentation. The system converts raw Mermaid text found within the source PDF into visual PNG assets for inclusion in the static visual guide.
This integration allows the project to maintain technical diagrams as version-controlled code rather than static images, ensuring that the visual representations of the "Corpus Ingestion and Embedding Flow" and "Natural Language to Code Entity Mapping" remain synchronized with the underlying architecture.
Sources: README.md:46-56, diagram_inventory.json:14-20
Architecture and Pipeline
The rendering pipeline operates during the optional site rebuild workflow. It specifically targets Mermaid source snippets that are printed as text within the GestaltView_Master_Wiki_v4.0.pdf on page 78.
Component Roles
- build_story_artifact.py: Orchestrates the extraction of Mermaid source blocks and manages the execution of the rendering utility.
- manus-render-diagram: An external utility responsible for converting
.mmdsource files into.pngimages. This utility must be available in the environment for the rebuild to succeed. - story_assets/: Serves as the destination directory for rendered Mermaid images.
- diagram_inventory.json: Records metadata for each Mermaid snippet, including confidence notes and source provenance.
Sources: build_story_artifact.py:270-280, README.md:48-52
Rendering Workflow
The following diagram illustrates the flow from raw PDF text to a rendered visual asset embedded in the final application.
The diagram shows the sequential steps taken by the build script to transform text-based Mermaid definitions into static web assets.
Sources: build_story_artifact.py:270-295, build_story_artifact.py:315-320
Data Structures and Configuration
The system uses specific data structures to track the Mermaid snippets and ensure high-fidelity rendering. These are defined within the builder script and persisted in the inventory.
Mermaid Source Metadata
| Field | Description | Source Reference |
|---|---|---|
id | Unique identifier for the diagram (e.g., corpus-ingestion-flow) | build_story_artifact.py:202 |
kind | Categorized as mermaid_source | diagram_inventory.json:522 |
mermaid_source | The raw graph definition text (e.g., graph TD) | diagram_inventory.json:537 |
confidence | Rated as high based on node label matching | diagram_inventory.json:524 |
Sources: diagram_inventory.json:521-540, build_story_artifact.py:200-220
Implementation of render_mermaid_items
The rendering logic is encapsulated in the render_mermaid_items function. It performs file I/O and sub-process management to interface with the rendering engine.
def render_mermaid_items() -> list[dict[str, Any]]:
items = []
for spec in MERMAID_SOURCES:
source_path = ASSET_DIR / f"{spec['id']}.mmd"
image_path = ASSET_DIR / f"{spec['id']}.png"
source_path.write_text(spec["source"], encoding="utf-8")
result = subprocess.run(["manus-render-diagram", str(source_path), str(image_path)], capture_output=True, text=True)
if result.returncode:
raise RuntimeError(f"Mermaid render failed for {spec['title']}: {result.stderr or result.stdout}")
# ... items mapping logic ...
return items
Sources: build_story_artifact.py:270-280
Execution and Validation
The build process validates the count of rendered Mermaid snippets to ensure documentation coverage. The inventory expects exactly 2 Mermaid source snippets out of a total of 54 visuals.
This sequence shows the interaction between the script and external utilities to ensure every Mermaid block is accounted for.
Sources: build_story_artifact.py:328-333, README.md:58-64
Diagnostic Requirements
If the manus-render-diagram utility is missing from the environment, the build process terminates with a RuntimeError. The resulting index.html remains self-contained because the rendered images are Base64 encoded and embedded during the final assembly step.
Sources: build_story_artifact.py:277-279, README.md:51-53
Conclusion
Mermaid Rendering Integration enables the GestaltView project to bridge the gap between text-based architectural definitions and visual aids. By using manus-render-diagram and build_story_artifact.py, the system ensures that complex flows like corpus ingestion are accurately represented in the interactive storytelling layer without requiring manual image maintenance.