Microsim Utils

MicroSim Utilities

Overview

This meta-skill provides utility functions for managing and maintaining MicroSims in intelligent textbook projects. It consolidates four utility skills into a single entry point with on-demand loading of specific utility guides.

When to Use This Skill

Use this skill when users request:

• Validating MicroSim quality and standards
• Capturing screenshots for preview images
• Adding or managing icons for MicroSims
• Generating index pages for MicroSim directories
• Quality scoring and standardization checks

Step 1: Identify Utility Type

Match the user's request to the appropriate utility guide:

Routing Table

Decision Tree

Need to check MicroSim quality/standards?
  → YES: standardization.md

Need to capture screenshots for previews?
  → YES: screen-capture.md

Need to add or manage icons?
  → YES: add-icons.md

Need to generate/update the MicroSim index page?
  → YES: index-generator.md

Step 2: Load the Matched Guide

Read the corresponding guide file from references/ and follow its workflow.

Step 3: Execute Utility

Each guide contains: 1. Purpose and use cases 2. Prerequisites 3. Step-by-step workflow 4. Output format 5. Best practices

Available Utilities

standardization.md

Purpose: Validate MicroSim quality against standards

Checks:

• Required file presence (main.html, index.md)
• Code structure and patterns
• Accessibility features
• Documentation completeness
• Responsive design implementation

Output: Quality score (0-100) with recommendations

screen-capture.md

Purpose: Capture high-quality screenshots for social media previews

Features:

• Uses Chrome headless mode
• Handles JavaScript-heavy visualizations
• Waits for proper rendering
• Creates consistent image sizes

Output: PNG screenshot in MicroSim directory

add-icons.md

Purpose: Add favicon and icons to MicroSim directories

Creates:

• favicon.ico
• apple-touch-icon.png
• Other platform-specific icons

index-generator.md

Purpose: Generate comprehensive MicroSim index page

Creates:

• Grid-based card layout
• Screenshots for each MicroSim
• Alphabetically sorted entries
• MkDocs Material card format
• Updates mkdocs.yml navigation

Examples

Example 1: Quality Check

User: "Check if my bouncing-ball MicroSim meets standards" Routing: Keywords "check", "standards" → references/standardization.md Action: Read standardization.md and follow its workflow

Example 2: Capture Screenshot

User: "Create a preview image for the timeline MicroSim" Routing: Keywords "preview", "image" → references/screen-capture.md Action: Read screen-capture.md and follow its workflow

Example 3: Update Index

User: "Update the MicroSim index page with all new sims" Routing: Keywords "index", "update" → references/index-generator.md Action: Read index-generator.md and follow its workflow

Common Workflows

After Creating New MicroSim

1. Run standardization.md to validate quality 2. Run screen-capture.md to create preview image 3. Run index-generator.md to add to index page

Bulk Quality Audit

Use standardization.md to audit all MicroSims in a project and generate a quality report.

Integration Notes

These utilities work with the standard MicroSim directory structure:

docs/sims/<microsim-name>/
├── main.html       # Main visualization
├── index.md        # Documentation
├── *.js            # JavaScript code
├── style.css       # Styles (optional)
└── <name>.png      # Preview screenshot (created by screen-capture)

MicroSim Add Icons

Overview

Add clickable Creative Commons license and fullscreen navigation icons to the control region of an existing p5.js MicroSim. The icons appear in the lower right corner and use distance-based click detection. This adds approximately 40 lines of code to the simulation.

When to Use This Skill

Use this skill when:

• Adding license information access to a MicroSim
• Enabling fullscreen mode via an icon
• Enhancing a MicroSim with clickable UI elements
• Following the icons demo pattern from the MicroSims repository

Workflow

Step 1: Identify the Target MicroSim

Ask the user which MicroSim JavaScript file to modify, or identify it from context. The file should be a p5.js MicroSim following the standard pattern with:

• Global variables section
• setup() function
• draw() function
• windowResized() function

Step 2: Read the Existing File

Read the entire JavaScript file to understand its structure and identify where to add the icon code.

Step 3: Add Icon Variables

Add the following variables to the global variables section, after the existing slider variables:

// Icon variables
let iconSize = 24;
let iconMargin = 5;
let ccIconX, ccIconY;  // Creative Commons icon position
let fsIconX, fsIconY;  // Fullscreen icon position

Also add or update the sliderRightMargin variable:

let sliderRightMargin = 70;

This reserves space on the right side of sliders for the icons.

Step 4: Add drawIcons() Function

Add the complete drawIcons() function after the draw() function:

function drawIcons() {
  // Calculate icon positions (right to left)
  fsIconX = canvasWidth - iconMargin - iconSize/2;
  fsIconY = drawHeight + controlHeight/2;

  ccIconX = fsIconX - iconSize - iconMargin;
  ccIconY = fsIconY;

  // Draw Creative Commons icon
  fill('black');
  noStroke();
  textAlign(CENTER, CENTER);
  textSize(20);
  text('ⓒ', ccIconX, ccIconY);
  // Draw Fullscreen icon
  text('⛶', fsIconX, fsIconY);
}

Step 5: Call drawIcons() in draw()

Add the following code at the end of the draw() function, just before the closing brace:

  // Draw icons in lower right corner of control region
  drawIcons();
}

Step 6: Add mousePressed() Function

Add the complete mousePressed() function after the drawIcons() function:

function mousePressed() {
  // Check if Creative Commons icon was clicked
  let distCC = dist(mouseX, mouseY, ccIconX, ccIconY);
  if (distCC < iconSize/2) {
    // Get the base URL (remove '/sims/icons/main.html' from current URL)
    let baseUrl = window.location.href.split('/sims/')[0];
    window.open(baseUrl + '/license/', '_blank');
    return;
  }

  // Check if Fullscreen icon was clicked
  let distFS = dist(mouseX, mouseY, fsIconX, fsIconY);
  if (distFS < iconSize/2) {
    // Open main.html in a new window/tab (same behavior as the fullscreen button)
    window.open('main.html', '_blank');
    return;
  }
}

Step 7: Update windowResized() Function

Update the windowResized() function to use sliderRightMargin when resizing sliders:

function windowResized() {
  // Update canvas size when the container resizes
  updateCanvasSize();
  resizeCanvas(containerWidth, containerHeight);
  // resize the speed slider and any other sliders here
  speedSlider.size(canvasWidth - sliderLeftMargin - sliderRightMargin);
  redraw();
}

If there are multiple sliders, update all slider size calculations to use sliderRightMargin.

Step 8: Update setup() Function

If the slider size is set in setup(), update it to use sliderRightMargin:

speedSlider.size(canvasWidth - sliderLeftMargin - sliderRightMargin);

Step 9: Verify and Test

After making all changes: 1. Verify that all edits were successful 2. Inform the user that the icons have been added 3. Note that approximately 40 lines of code were added 4. Suggest testing the icons by opening the MicroSim

Code Size Impact

Adding icons increases the JavaScript file size by approximately 40 lines:

• 6 lines for icon variables
• 1 line to call drawIcons()
• 18 lines for the drawIcons() function
• 19 lines for the mousePressed() function
• Additional spacing and comments

The icons can be omitted from minimal MicroSims to reduce file size.

Icon Functionality

Creative Commons Icon (ⓒ):

• Positioned second from the right in the control region
• Clicking opens /license/ page in a new tab
• Uses relative URL calculation to work in any deployment

Fullscreen Icon (⛶):

• Positioned at the far right of the control region
• Clicking opens main.html in a new window/tab
• Provides full-page viewing experience

Both icons use distance-based click detection with dist() function, creating circular clickable regions with a radius of iconSize/2 (12 pixels).

Common Variations

Different Icon Symbols: Replace the Unicode characters ⓒ and ⛶ with other symbols as needed:

• License: ⓒ, ©, 🅭
• Fullscreen: ⛶, ⤢, ⛶
• Help: ?, ⓘ, ❓
• Settings: ⚙, ⚙️

Additional Icons: To add more icons, follow the same pattern: 1. Add position variables (e.g., helpIconX, helpIconY) 2. Calculate position in drawIcons() (move left by iconSize + iconMargin) 3. Draw the icon in drawIcons() 4. Add click detection in mousePressed() 5. Increase sliderRightMargin by 30 pixels per additional icon

Custom Actions: Modify the mousePressed() function to perform different actions:

• Open different URLs
• Toggle simulation features
• Display help overlays
• Share via social media

MicroSims Index Generator

Overview

This skill automates the creation and maintenance of a MicroSims index page for intelligent textbooks built with MkDocs Material theme. It scans the /docs/sims/ directory, captures screenshots for MicroSims missing preview images, and generates a professionally formatted index page using mkdocs-material grid cards.

When to Use This Skill

Use this skill when:

• A new MicroSim has been added and the index needs updating
• Multiple MicroSims exist but lack preview screenshots
• The MicroSims index page needs to be reformatted to grid cards
• The mkdocs.yml navigation section for MicroSims needs synchronization

Prerequisites

• MkDocs project with Material theme configured
• attr_list and md_in_html markdown extensions enabled in mkdocs.yml
• MicroSims located in /docs/sims/<microsim-name>/ directories
• Each MicroSim directory contains:
• main.html - The interactive simulation
• index.md - Documentation page with title and description
• Screenshot capture tool available at ~/.local/bin/bk-capture-screenshot

Workflow

Step 0: Verify mkdocs.yml Extensions

Before generating the index, verify that mkdocs.yml has the required markdown extensions for grid cards to render properly:

markdown_extensions:
  - attr_list
  - md_in_html

Check the file:

grep -A 20 "markdown_extensions:" mkdocs.yml

If either attr_list or md_in_html is missing, add them to the markdown_extensions section before proceeding. Grid cards will not render without these extensions.

Step 1: Discover MicroSims

List all MicroSim directories in /docs/sims/:

ls /path/to/project/docs/sims/

Exclude the index.md file from the list. Each subdirectory represents a MicroSim.

Step 2: Gather MicroSim Information

For each MicroSim directory, read the index.md file to extract:

1. Title - From the first H1 heading or YAML frontmatter title 2. Description - A short 1-2 sentence summary from the content

Example structure to look for:

# MicroSim Title

Description paragraph explaining what the MicroSim does...

Step 3: Check for Missing Screenshots

For each MicroSim, check if a PNG screenshot exists:

ls /path/to/project/docs/sims/<microsim-name>/*.png

The screenshot filename should match the directory name (e.g., command-syntax/command-syntax.png).

Step 4: Capture Missing Screenshots

For each MicroSim missing a screenshot, use the screenshot capture tool:

~/.local/bin/bk-capture-screenshot /path/to/project/docs/sims/<microsim-name>

This tool:

• Captures a 1200x800 screenshot of main.html using Chrome headless
• Waits 3 seconds for JavaScript to load
• Saves as <microsim-name>.png in the MicroSim directory

For MicroSims with complex animations, increase the delay:

~/.local/bin/bk-capture-screenshot /path/to/project/docs/sims/<microsim-name> 5

Step 5: Generate Index Page Content

Create the index page at /docs/sims/index.md using mkdocs-material grid cards format.

Required YAML Frontmatter

IMPORTANT: Image paths must use the format /sims/NAME/NAME.png where NAME is the kebab-case name. For the index page itself, use /sims/index-screen-image.png or similar.

---
title: List of MicroSims for [Course Name]
description: A list of all the MicroSims used in the [Course Name] course
image: /sims/index-screen-image.png
og:image: /sims/index-screen-image.png
hide:
    toc
---

For individual MicroSim index.md files, the image paths should follow this format:

---
title: Bouncing Ball
description: A MicroSim of a ball bouncing...
image: /sims/bouncing-ball/bouncing-ball.png
og:image: /sims/bouncing-ball/bouncing-ball.png
---

Grid Cards Structure

# List of MicroSims for [Course Name]

Interactive Micro Simulations to help students learn [subject] fundamentals.

<div class="grid cards" markdown>

-   **[MicroSim Title](./microsim-name/index.md)**

    ---

    ![MicroSim Title](./microsim-name/microsim-name.png)

    Short description of what the MicroSim does and teaches.

</div>

Card Item Format

Each card follows this exact structure (order matters):

1. Title with link - Bold linked title 2. Horizontal rule - --- separator 3. Image - Screenshot with alt text matching title 4. Description - 1-2 sentence summary

Example card:

-   **[Command Syntax Visual Guide](./command-syntax/index.md)**

    ---

    ![Command Syntax Visual Guide](./command-syntax/command-syntax.png)

    Color-coded breakdown of Linux command structure showing commands, options, and arguments with hover explanations.

Step 6: Sort Alphabetically

Sort all MicroSim cards alphabetically by their title. This ensures consistent ordering across the index page and navigation.

Step 7: Update mkdocs.yml Navigation

Locate the MicroSims section in mkdocs.yml and update it with alphabetically sorted entries:

  - MicroSims:
    - List of Microsims: sims/index.md
    - Bash vs Zsh: sims/bash-vs-zsh/index.md
    - Command Syntax Guide: sims/command-syntax/index.md
    # ... additional entries alphabetically

Keep "List of Microsims" as the first entry, then sort remaining items alphabetically.

Output Files

This skill creates or updates:

1. /docs/sims/index.md - The main MicroSims index page 2. /docs/sims/<name>/<name>.png - Screenshot for each MicroSim (if missing) 3. mkdocs.yml - Updated navigation section for MicroSims

Example Output

A complete index page for a Linux course with 12 MicroSims:

---
title: List of MicroSims for Learning Linux
description: A list of all the MicroSims used in the Teaching Linux course
image: /sims/index-screen-image.png
og:image: /sims/index-screen-image.png
hide:
    toc
---
# List of MicroSims for Learning Linux

Interactive Micro Simulations to help students learn Linux fundamentals.

<div class="grid cards" markdown>

-   **[Bash vs Zsh Comparison](./bash-vs-zsh/index.md)**

    ---

    ![Bash vs Zsh Comparison](./bash-vs-zsh/bash-vs-zsh.png)

    Side-by-side comparison of `bash` and `zsh` shells with star ratings for compatibility, features, and customization.

-   **[Command Syntax Visual Guide](./command-syntax/index.md)**

    ---

    ![Command Syntax Visual Guide](./command-syntax/command-syntax.png)

    Color-coded breakdown of Linux command structure showing commands, options, and arguments with hover explanations.

</div>

Troubleshooting

Screenshot Capture Fails

If screenshot capture fails: 1. Verify Chrome/Chromium is installed 2. Check that main.html exists in the MicroSim directory 3. Increase delay for JavaScript-heavy simulations 4. Check for CDN loading issues (may need network access)

Grid Cards Not Rendering

Ensure mkdocs.yml has required extensions:

markdown_extensions:
  - attr_list
  - md_in_html

Images Not Displaying

Verify image paths use relative format: ./microsim-name/microsim-name.png

MicroSim Screen Capture

Overview

This skill automates the process of capturing high-quality screenshots of MicroSim visualizations using Chrome headless mode. It properly handles dynamic JavaScript content, external CDN libraries (like vis-network.js, p5.js, Chart.js), and ensures the visualization has time to fully render before capturing.

When to Use This Skill

Use this skill when:

• Creating preview images for MicroSims that need social media metadata (og:image)
• Generating screenshots for MicroSim documentation
• Capturing visualizations for quality assessment or archival purposes
• Working with the microsim-standardization skill to achieve a perfect 100/100 quality score

Typical user requests:

• "Create a screenshot of this MicroSim"
• "I need a preview image for the org-chart MicroSim"
• "Generate a social media preview for this visualization"
• "Capture a screenshot of the main.html file"

Workflow

Step 1: Validate the MicroSim Directory

Before capturing a screenshot, verify:

1. The MicroSim directory exists at the provided path (typically docs/sims/{microsim-name}/) 2. The directory contains a main.html file 3. The MicroSim name follows kebab-case convention (lowercase letters and dashes only)

Step 2: Run the Screenshot Capture Script

Execute the provided shell script with the MicroSim directory path:

bash scripts/capture-screenshot.sh <microsim-directory-path>

Example:

bash scripts/capture-screenshot.sh $HOME/Documents/ws/intro-to-graph/docs/sims/org-chart

The script will:

1. Extract the MicroSim name from the directory path (e.g., org-chart from .../sims/org-chart/) 2. Locate the main.html file in the directory 3. Use Chrome headless mode with optimal flags for JavaScript visualization rendering 4. Save the screenshot as {microsim-name}.png in the MicroSim directory (e.g., org-chart.png) 5. Display the output file path and size upon success

Important Chrome flags used:

• --headless=new: Uses the modern headless mode
• --disable-web-security + --allow-file-access-from-files: Allows loading external CDN resources (critical for vis-network, p5.js, etc.)
• --timeout=5000: Gives JavaScript 5 seconds to load and render the visualization
• --window-size=1200,800: Sets a standard viewport size suitable for social media previews
• --hide-scrollbars: Ensures clean screenshots without scrollbar artifacts

Step 3: Verify the Screenshot

After the script completes:

1. Check that the image file was created: {microsim-name}.png 2. Verify the file size is reasonable (typically 20-100KB for rendered visualizations) 3. Use the Read tool to view the screenshot and confirm the visualization rendered properly 4. If the visualization area appears blank/white, the JavaScript may need more time to render - try increasing the --timeout value in the script

Step 4: Update MicroSim Metadata (Optional)

If capturing the screenshot as part of MicroSim standardization, update the index.md YAML frontmatter:

---
title: MicroSim Title
description: Brief description
image: microsim-name.png
og:image: microsim-name.png
quality_score: 100
---

This adds the social media preview metadata and contributes 10 points toward the quality score (5 points for metadata fields + 5 points for the image file existing).

Troubleshooting

Screenshot captures but visualization is blank

Problem: The screenshot shows the page header/controls but the main visualization area is white/empty.

Solutions: 1. Increase the timeout value in the script (change --timeout=5000 to --timeout=10000) 2. Check browser console for JavaScript errors (the script filters them out but they may indicate issues) 3. Verify the visualization works when opening main.html directly in a browser 4. For very complex visualizations, consider using --virtual-time-budget=10000 instead of --timeout

Chrome not found error

Problem: Script reports "Chrome/Chromium not found"

Solutions: 1. Install Google Chrome if not present 2. Update the CHROME_PATHS array in the script to include your Chrome installation path 3. On macOS, Chrome is typically at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

External resources not loading

Problem: Visualizations that use CDN libraries (vis-network, p5.js, Chart.js) don't render

Solution: The script already includes --disable-web-security and --allow-file-access-from-files flags which should allow CDN resources. If still not working: 1. Verify internet connectivity (CDNs need to be accessible) 2. Check if the library CDN URL is valid in main.html 3. Try using a localhost server instead of file:// URLs (see Advanced Usage below)

Advanced Usage: Using localhost Instead of file:// URLs

For MicroSims that have issues with file:// URLs, serve the content via HTTP:

# Start a local server in the project root
cd /path/to/project-root
python -m http.server 8000 &

# Modify the script to use localhost URL
# Replace: "file://$ABSOLUTE_PATH"
# With: "http://localhost:8000/docs/sims/microsim-name/main.html"

# Capture screenshot
bash scripts/capture-screenshot.sh /path/to/microsim

# Stop the server
pkill -f "http.server"

Technical Details

Why Chrome Headless?

Chrome headless mode is used because: 1. JavaScript Support: Full Chrome rendering engine handles complex JavaScript visualizations 2. CDN Loading: Can fetch external resources from CDNs (with proper flags) 3. Timing Control: Can wait for async content to load before capturing 4. Cross-platform: Works on macOS, Linux, and Windows 5. No GUI Required: Can run in CI/CD environments

Screenshot Naming Convention

The script names screenshots using the MicroSim directory name to maintain consistency:

• MicroSim: docs/sims/org-chart/ → Screenshot: org-chart.png
• MicroSim: docs/sims/learning-graph-viewer/ → Screenshot: learning-graph-viewer.png

This differs from using a generic name like preview.png because: 1. Makes the file purpose immediately clear when viewing the directory 2. Easier to identify which screenshot belongs to which MicroSim in bulk operations 3. Follows naming conventions used elsewhere in the project

Default Screenshot Dimensions

The default viewport size is 1200x800 pixels because:

• Width (1200px): Standard desktop viewport, suitable for most visualizations
• Height (800px): Captures header + controls + visualization without excessive whitespace
• Aspect Ratio (3:2): Works well for social media og:image tags
• File Size: Produces reasonably sized PNG files (typically 20-100KB)

To customize dimensions, modify the --window-size flag in the script.

Resources

scripts/capture-screenshot.sh

Bash script that automates the entire screenshot capture process. The script:

• Validates input and checks for required files
• Locates Chrome/Chromium across different platforms
• Constructs proper file:// URLs with absolute paths
• Runs Chrome headless with optimized flags for JavaScript visualizations
• Reports success/failure with file size information

The script is designed to be:

• Self-contained: No external dependencies beyond Chrome
• Cross-platform: Works on macOS, Linux, and Windows (with minor path adjustments)
• Error-tolerant: Filters out common Chrome headless warnings that don't affect functionality
• User-friendly: Clear error messages and success indicators

MicroSim Standardization

Overview

This skill validates and standardizes MicroSim directories to ensure they meet quality and documentation standards. MicroSims are interactive educational simulations that may use various JavaScript libraries (p5.js, vis-network, Chart.js, etc.). This skill performs a comprehensive audit of a MicroSim directory, generates a TODO list of required upgrades, and optionally implements the standardization changes. After this process runs, a quality_score will be added to the index.md metadata. A rubric of how the quality score is provided and this score should be shown to the user before and after the changes.

Note on Terminology

There are two types of metadata for a MicroSim. 1. yml header metadata: - this metadata is inserted into the top of the index.md file. This is to support the social image previews. The mkdocs social_preview extension uses these fields. The quality_score is also stored here. 2. :Dublin core metadata - These metadata elements are ONLY stored in the metadata.json file.

Do not mix these up! Never put Dublin Core metadata into the yml headers.

Workflow

Step 1: Receive MicroSim Directory Path

Receive the path to the MicroSim directory from the user. The directory should be located at:

• docs/sims/[microsim-name]/

Note that the microsim-name must be a string with only lowercase letters and dashes (kebab-case)

2: Check for an Existing Quality Score

Check of a quality_score of 85 or above exists in the yml metadata of the index.md file like this:

---
quality_score: 86
---

If the score is 85 or above, suggest to the user to skip the rest of the steps. Tell them that perhaps their tokens can be better used to create new MicroSims.

If the score is missing or lower than 85, proceed with the next steps.

Confirm the directory exists and contains at minimum a main.html file (the core simulation file).

Step 3: Run Standardization Checklist

Run through the complete standardization checklist, documenting which items pass and which need work. Use the TodoWrite tool to create a comprehensive TODO list of all items that need to be addressed. Store the TODO list in TODO.txt in the MicroSim directory.

Standardization Checklist:

1. Index.md File Existence

• Check if index.md file exists in the MicroSim directory
• If missing: Add TODO to create index.md file

2. YAML metadata at the top of the index.md

• Verify index.md begins with YAML frontmatter (between --- delimiters)
• Required YAML fields:
• title: - MicroSim title
• description: - Brief description for SEO and social previews
• quality_score: - Integer 1-100 indicating completeness/quality
• image: and og:image - Social media preview image path (optional but recommended)
• IMPORTANT: Image paths must use the format /sims/NAME/NAME.png where NAME is the kebab-case MicroSim name
• Example for a MicroSim named "bouncing-ball":

      image: /sims/bouncing-ball/bouncing-ball.png
      og:image: /sims/bouncing-ball/bouncing-ball.png

• If missing or incomplete: Add TODO to add/fix YAML frontmatter

3. Level 1 Header After Frontmatter

• Verify a level 1 header (# Title) appears immediately after YAML metadata
• The title should match or complement the YAML title field
• If missing: Add TODO to add level 1 header

4. Iframe Embed After Title

• Check for iframe element after the level 1 title
• Iframe must reference main.html
• Standard format:

  <iframe src="main.html" width="100%" height="600px"></iframe>

• If missing or incorrect: Add TODO to add/fix iframe embed

Note: Do not add the frameborder attribute to the iframe. The site-wide CSS is responsible for styling all iframes with the site.

5. Copy-Paste Iframe Example

• Check for a second iframe in an HTML code block with label "Copy this iframe to your website:"
• This allows users to embed the MicroSim in their own sites
• Standard format:

````markdown

  <iframe src="https://your-domain.github.io/path/to/sims/microsim-name/main.html" width="100%" height="600px"></iframe>

````

• If missing: Add TODO to add copy-paste iframe example

6. Metadata.json File Existence

• Check if metadata.json file exists in the MicroSim directory
• If missing: Add TODO to create metadata.json with Dublin Core metadata

7. Metadata.json Schema Validation

• Validate metadata.json against the Dublin Core schema in assets/metadata-schema.json
• Required Dublin Core fields:
• title - MicroSim name
• description - Purpose and functionality
• creator - Author name or organization
• date - Creation date (ISO 8601: YYYY-MM-DD)
• subject - Keywords or topics (string or array)
• type - Resource type (e.g., "Interactive Simulation")
• format - File format (e.g., "text/html")
• language - Language code (e.g., "en" or "en-US")
• rights - License information (e.g., "CC BY 4.0", "MIT License")
• If validation fails: Add TODO to fix metadata.json structure and content

8. Fullscreen Link Button

• Check for fullscreen link button after the iframe example
• Standard format:

  [Run MicroSim in Fullscreen](main.html){ .md-button .md-button--primary }

• If missing: Add TODO to add fullscreen link button

9. P5.js Editor Link (P5.js MicroSims Only)

• Determine if the MicroSim uses p5.js by checking:
• Import statements in main.html for p5.js CDN
• Use of p5.js functions like setup(), draw(), createCanvas()
• If p5.js is used, check for p5.js editor link:

  [Edit in the p5.js Editor](https://editor.p5js.org/username/sketches/SKETCH_ID)

• If link is missing or placeholder: Add TODO to prompt user for p5.js sketch path
• If not a p5.js MicroSim: Skip this check

10. Description Section (Level 2 Header)

• Check for a level 2 header section (e.g., ## Description, ## How to Use, ## About This MicroSim) after the frontmatter elements
• This section should describe the MicroSim's purpose, how to use it, and what concepts it demonstrates
• If missing: Add TODO to add description section

11. Lesson Plan Section

• Check if a ## Lesson Plan level 2 header exists
• This section should include:
• Learning objectives
• Target audience
• Prerequisites
• Activities or exercises
• Assessment suggestions
• If missing: Add TODO to ask user whether to create a lesson plan section

12. References Section

• Check if a ## References level 2 header exists at the end of the document
• This section should include:
• Links to relevant academic papers or articles
• Links should be in the format 1. [Link Title](URL) - publication_date - publication_name - description and relevency
• Documentation for libraries used
• Related educational resources
• If missing and appropriate for the content: Add TODO to add references section

Step 4: Present TODO List to User

Present the comprehensive TODO list to the user, organized by priority: 1. Critical structural issues (missing index.md, invalid metadata.json) 2. Required documentation elements (frontmatter, headers, iframes) 3. Enhanced documentation (lesson plans, references)

Ask the user: "Should I proceed with implementing these standardization changes? (y/n)"

Step 5: Implement Changes (If Approved)

If the user responds "y" or "yes":

1. Work through the TODO list systematically 2. Update the TodoWrite status as each item is completed 3. For items requiring user input (e.g., p5.js sketch URL, lesson plan content details), use AskUserQuestion to gather necessary information 4. Validate all changes as they're made 5. Re-run metadata.json validation after modifications

Implementation Guidelines:

• Preserve existing content: Never remove or overwrite user content without explicit confirmation
• Maintain formatting consistency: Use the same markdown style as existing content
• Add blank lines before lists: MkDocs requires blank lines before markdown lists
• Use Title Case for headers: Follow MkDocs Material theme conventions
• Validate JSON syntax: Ensure metadata.json is valid JSON before saving
• Test iframe paths: Verify main.html path is correct relative to index.md

Step 6: Final Validation and Quality Report

After completing all changes:

1. Run final validation on metadata.json using the schema 2. Check that all TODO items are marked completed 3. Provide a summary report to the user:

• Number of issues found and fixed
• Any items that require follow-up
• Suggested quality_score for the YAML frontmatter (based on completeness)

After the score is calculated, it must be written to the index.md metadata quality_score field

Resources

assets/metadata-schema.json

JSON Schema for validating MicroSim metadata.json files against Dublin Core standards. This schema defines:

• Required fields (9 core Dublin Core elements)
• Optional fields (extended metadata for educational resources)
• Field types and validation patterns
• Educational extensions (Bloom's levels, concepts, prerequisites)

Use this schema to validate metadata.json files programmatically or to guide manual validation.

assets/index-template.md

Complete template showing the standard structure for a MicroSim index.md file, including:

• YAML frontmatter with all required fields
• Level 1 header
• Iframe embeds (both display and copy-paste versions)
• Fullscreen link button
• Description section with usage instructions
• Lesson Plan section with learning objectives, activities, and assessment
• References section

Use this template when creating new index.md files or when a MicroSim is missing critical documentation sections.

assets/metadata-template.json

Complete template showing all Dublin Core metadata fields with example values, including:

• All 9 required core fields
• Optional contributor and identifier fields
• Educational extensions (Bloom's levels, concepts, prerequisites, library)

Use this template when creating new metadata.json files or when existing metadata is incomplete.

Notes

• Quality Score Guidance: Assign quality scores based on completeness:
• 90-100: All checklist items present, excellent documentation, lesson plan included
• 70-89: Most items present, good documentation, may lack lesson plan
• 50-69: Core items present, minimal documentation
• Below 50: Missing critical components

• Library Detection: Detect JavaScript libraries by checking for:
• p5.js: p5.js or p5.min.js in script tags
• vis-network: vis-network in script tags or imports
• Chart.js: chart.js or Chart.min.js in script tags
• D3.js: d3.js or d3.min.js in script tags

• Metadata Best Practices:
• Use ISO 8601 dates (YYYY-MM-DD)
• Include multiple subject keywords for discoverability
• Specify clear educational levels and prerequisites
• List all contributors, not just the primary creator
• Include version numbers for tracking iterations