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