microsims-index-generator_skill

Overview

This skill generates and maintains a MicroSims index page for MkDocs Material-based textbooks. It scans /docs/sims/, extracts titles and descriptions, captures missing screenshots, and builds an alphabetically sorted grid-card index. It also synchronizes the MicroSims section in mkdocs.yml so navigation and index stay consistent.

How this skill works

The skill discovers each MicroSim directory under /docs/sims/, reads index.md to extract the title and a short description, and checks for a matching PNG screenshot. If a screenshot is missing, it invokes a headless Chrome capture tool to produce a 1200x800 PNG of main.html (with configurable delay). Finally it generates /docs/sims/index.md using mkdocs-material grid cards and updates the mkdocs.yml MicroSims navigation entries in alphabetical order.

When to use it

• After adding one or more new MicroSims directories
• When MicroSims lack preview screenshots
• To convert or reformat the MicroSims page into mkdocs-material grid cards
• When mkdocs.yml navigation for MicroSims is out of sync
• Before a site build or deployment to ensure screenshots and index are up to date

Best practices

• Enable attr_list and md_in_html markdown extensions in mkdocs.yml before generating the index
• Keep each MicroSim directory organized with main.html and index.md (title in H1 or frontmatter)
• Name screenshots to match their directory (e.g., microsim-name/microsim-name.png) to allow predictable linking
• Run screenshot capture on a machine with Chrome/Chromium installed and sufficient network access for resources
• Increase capture delay for simulations that load assets or animations asynchronously

Example use cases

• Regenerate the MicroSims index after bulk adding 10 new simulations to /docs/sims/
• Automatic screenshot creation for simulations missing preview images prior to publishing
• Standardize the MicroSims index format to mkdocs-material grid cards for a course site
• Synchronize mkdocs.yml navigation after renaming or reordering MicroSims directories
• Run a pre-release check to ensure all MicroSims have titles, descriptions, and screenshots