microsims-index-generator

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

---
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
---

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