Adding New Diagrams to the Inventory
Relevant source files
The following files were used as context for generating this wiki page:
Adding new diagrams to the GestaltView Visual Story involves updating the central diagram_inventory.json and generating new visual assets from the master PDF. This process ensures that the static guide remains synchronized with the latest architectural changes in the GestaltView Master Wiki v4.0. The system categorizes visuals into curated opening diagrams, captioned figures, and Mermaid source snippets.
The pipeline utilizes a Python-based builder to extract images and metadata, which are then injected into a self-contained HTML artifact.
Rebuild Pipeline Overview
The rebuild workflow transforms a source PDF into a structured JSON inventory and a standalone index.html. You must have the source PDF GestaltView_Master_Wiki_v4.0.pdf and the necessary Python dependencies to execute this process.
The diagram above shows the data flow from the source PDF to the final static site deployment.
Adding Curated Opening Diagrams
Curated diagrams appear in the "Get Oriented" section and include detailed part-level explanations. To add a new curated diagram, you must modify the hardcoded metadata within the builder script.
Update Metadata Dictionaries
- Map Page Numbers: Add the PDF page number, title, and associated chapter ID to the
CURATEDdictionary. - Add Explanations: Provide text for the "Orientation", "System", and "Architecture" lenses in the
CURATED_COPYdictionary. - Define Parts: List specific key ideas and their meanings in the
CURATED_PARTSdictionary.
Sources: build_story_artifact.py:18-185
Implementation Logic
The builder identifies curated sections by searching for text blocks that match the regex ^(\d{1,2})\.\s+ with a font size greater than 13.0. It then crops the page area between the heading and the next identified section.
Sources: build_story_artifact.py:246-285
Adding Captioned Figures
Captioned figures are automatically discovered by the builder if they follow the standard naming convention.
Requirements for Auto-Discovery
To ensure a figure is indexed, it must meet these criteria in the PDF:
- It must have a caption starting with "Figure [Number]:".
- The text must be recognizable by the
pymupdfparser.
The builder uses the regex ^Figure\s+([\d.]+)\s*:\s*(.+)$ to extract the figure number and title.
Sources: build_story_artifact.py:304-315
Extraction Process
- The script locates the caption block on a page.
- It identifies the nearest heading preceding the caption to determine the section.
- It calculates a crop rectangle covering the visual content above the caption.
- It extracts the surrounding text to provide context in the "System" lens.
Sources: build_story_artifact.py:304-350
Adding Mermaid Source Snippets
The repository supports rendering Mermaid diagrams directly from text snippets found in the PDF.
Configuration
Add a new entry to the MERMAID_SOURCES list in build_story_artifact.py. Each entry requires:
id: A unique alphanumeric string.title: The display name for the diagram.page: The source page number for reference.source: The raw Mermaid code (e.g.,graph TD).
Sources: build_story_artifact.py:202-225
Rendering Tooling
The builder calls an external utility, manus-render-diagram, to convert the .mmd source file into a .png asset. You must ensure this utility is available in your environment path during the rebuild.
Sources: README.md:50-52, build_story_artifact.py:355-365
Data Structures and Types
The diagram_inventory.json file serves as the single source of truth for all visuals.
| Field | Type | Description |
|---|---|---|
id | String | Unique identifier (e.g., curated-01 or figure-p015-1...) |
kind | String | Type of visual: curated, captioned_figure, or mermaid_source |
page | Integer | The 1-based page number in the source PDF |
explanations | Object | Contains orientation, system, and architecture strings |
asset_path | String | Relative path to the image file in story_assets/ |
parts | Array | (Curated only) List of labels and part-specific explanations |
Sources: diagram_inventory.json:10-50, build_story_artifact.py:280-298
Validation and Testing
After running the builder, you must validate the inventory to ensure no regressions occurred.
- Check Counts: The builder prints the count of each item type. As of version 4.0, the inventory contains 13 curated, 39 captioned, and 2 Mermaid visuals.
- Run Tests: Execute the unit tests to verify asset presence, attribution, and navigation links.
python3 -m unittest discover -s tests -v - Verify Provenance: Consult
docs/SOURCE_PROVENANCE.mdto confirm the status of new diagrams.
Sources: README.md:55-63, build_story_artifact.py:397-402
The resulting index.html is a zero-dependency static file. It embeds all images as Base64 strings, allowing the guide to function entirely offline once built.