MicroSim File Relationship Diagram

How MicroSim Files Integrate into MkDocs Textbooks

This diagram shows how the three core MicroSim files (index.md, main.html, metadata.json) relate to each other and integrate into the MkDocs intelligent textbook architecture. The diagram illustrates the flow from student navigation through the documentation to the interactive simulation, including security boundaries and metadata cataloging.

flowchart TD MkDocs["MkDocs Navigation
Site Navigation Structure"]:::mkdocsNode IndexMD["index.md
📄 Documentation Page
Student navigates here"]:::docNode IFrame["iframe element
🔒 Security Boundary
Sandbox isolation"]:::iframeNode MainHTML["main.html
📝 Interactive HTML
Self-contained, interactive
Loads p5.js from CDN"]:::codeNode P5Sim["p5.js Simulation
🎨 Canvas Rendering
Interactive Visualization"]:::simNode Metadata["metadata.json
📋 Dublin Core Metadata
Discovery & cataloging"]:::metadataNode LMS["Learning Management System
External Integration"]:::lmsNode MkDocs -->|includes| IndexMD IndexMD -->|contains| IFrame IFrame -->|embeds| MainHTML MainHTML -->|renders| P5Sim Metadata -.->|describes| IndexMD Metadata -.->|can export to| LMS classDef mkdocsNode fill:#e9ecef,stroke:#495057,stroke-width:3px,color:#212529,font-size:16px classDef docNode fill:#4dabf7,stroke:#1864ab,stroke-width:3px,color:#fff,font-size:16px classDef iframeNode fill:#ff922b,stroke:#d9480f,stroke-width:3px,color:#fff,font-size:16px classDef codeNode fill:#51cf66,stroke:#2b8a3e,stroke-width:3px,color:#fff,font-size:16px classDef simNode fill:#ff6b6b,stroke:#c92a2a,stroke-width:3px,color:#fff,font-size:16px classDef metadataNode fill:#cc5de8,stroke:#862e9c,stroke-width:3px,color:#fff,font-size:16px classDef lmsNode fill:#adb5bd,stroke:#495057,stroke-width:2px,stroke-dasharray: 5 5,color:#212529,font-size:16px linkStyle 0,1,2,3 stroke:#495057,stroke-width:3px,font-size:16px linkStyle 4,5 stroke:#868e96,stroke-width:2px,stroke-dasharray: 5 5,font-size:16px

Component Descriptions

📄 index.md

Type: Documentation Page

Purpose: Student-facing documentation that provides context, instructions, and learning objectives for the MicroSim.

Location: docs/sims/{name}/index.md

Contains: Description, iframe embed, usage instructions, educational context

🔒 iframe element

Type: HTML Integration Point

Purpose: Provides security boundary and sandbox isolation for the interactive simulation.

Security: Prevents simulation from accessing parent page DOM

Note: Embedded within index.md using markdown/HTML

📝 main.html

Type: Interactive HTML Page

Purpose: Self-contained interactive visualization using p5.js or other libraries.

Location: docs/sims/{name}/main.html

Dependencies: Loads p5.js from CDN, includes simulation code

🎨 p5.js Simulation

Type: Canvas Rendering

Purpose: Interactive educational visualization rendered on HTML5 canvas.

Features: Real-time interaction, dynamic updates, visual feedback

Library: p5.js loaded from CDN

📋 metadata.json

Type: Dublin Core Metadata

Purpose: Provides structured metadata for discovery, cataloging, and LMS integration.

Location: docs/sims/{name}/metadata.json

Standards: Dublin Core, Bloom's Taxonomy

🌐 Learning Management System

Type: External Integration (Optional)

Purpose: Import MicroSim metadata into LMS for course organization and tracking.

Connection: Reads metadata.json for course integration

Examples: Canvas, Moodle, Blackboard

Relationship Flows

Primary Navigation Flow (Student Experience)

  1. MkDocs Navigation → Student browses textbook site navigation
  2. index.md → Student clicks link and lands on documentation page
  3. iframe element → Page displays embedded simulation via iframe
  4. main.html → Simulation loads in isolated sandbox
  5. p5.js Simulation → Student interacts with visual canvas

Metadata Flow (Discovery & Cataloging)

  1. metadata.json → Contains Dublin Core metadata fields
  2. index.md → Metadata describes the documentation page
  3. LMS Integration → External systems can import metadata for course catalogs

Security Boundaries

iframe Sandbox: The iframe element creates a security boundary that prevents the simulation (main.html) from accessing the parent MkDocs page. This isolation ensures:

  • Simulation code cannot modify site navigation
  • User data in the textbook remains protected
  • Simulation errors don't crash the entire page
  • Safe execution of untrusted or experimental code