Book Installer
Version: 1.0
Changelog
- v1.0 — First tracked version number for this skill. Adds
references/mascot-placement-rules.md as the single canonical source for when
and how often a learning mascot may appear, plus
scripts/render-mascot-guide.py (renders those rules into a book's
CONTENT-GENERATION-GUIDE.md between sentinel comments so the copy is
regenerated, never hand-edited). The per-chapter ceiling is raised from 6 to 9
admonitions for longer chapters, and scripts/validate-chapter-mascots.py now
reports the deprecated -encouraging spelling of the encourage pose class —
which mascot.css never defined, so it rendered unstyled — and exempts the
Chapter 1 self-introduction
from the 1-3 sentence cap it always violated. Version is tracked under
metadata: rather than a bare version: key, which strict packaging
validation rejects.
Overview
This meta-skill handles installation and setup tasks for intelligent textbook projects. It consolidates five installation skills into a single entry point with on-demand loading of specific installation guides.
When to Use This Skill
Use this skill when users request:
- Setting up a new MkDocs Material project
- Creating a new intelligent textbook from scratch (feature #0 scaffold)
- Installing a learning graph viewer
- Setting up skill usage tracking with hooks
- Registering the book with Google Analytics (GA4 Measurement ID)
- Bootstrapping project infrastructure
Step 1: Handle Help Requests
If the user asks for "help", "what can you do", or "list features", display this numbered list directly (do not load a reference file):
Book Installer Features (most → least common):
0. New textbook scaffold - complete mkdocs.yml + docs/ tree + license for an empty directory (run once at project birth)
1. Simple mkdocs.yml template - Minimal starter config for new projects (see feature 0)
2. Site logo - Add custom logo to header
3. Favicon - Browser tab/bookmark icon
3b. Generate favicon from mascot - Auto-generate favicon.ico from neutral.png mascot image
4. Cover image & social preview - Home page image + og:image metadata
4b. Generate cover image prompt - Create a prompt for generating a cover image using text-to-image AI (DALL-E, Midjourney, etc.)
4c. Social media preview hook - Inject og:* / twitter:* meta tags via MkDocs hook (no Cairo required)
5. Math equations - KaTeX (recommended) or MathJax
6. Code syntax highlighting - Language-aware code blocks
7. Code copy button - One-click copy for code blocks
8. Mermaid diagrams - Flowcharts, sequence diagrams from text
9. Content tabs - Tabbed sections for alternatives
10. Image zoom (GLightbox) - Click to enlarge images
11. Custom admonitions - Prompt boxes with copy button
12. Interactive quizzes - Self-assessment questions
13. Abbreviations & tooltips - Glossary hover definitions
14. Task lists - Checkbox lists
15. Simple feedback - Thumbs up/down per page
16. Detailed comments (Giscus) - GitHub Discussions integration
17. Tags & categorization - Page tagging system
18. Search enhancements - Suggestions and highlighting
19. Table of contents config - TOC sidebar options
20. Blog support - Add blog section
21. Announcement bar - Dismissible top banner
22. Privacy & cookie consent - GDPR compliance
23. Learning graph viewer - Interactive concept visualization
24. Skill usage tracker - Claude Code analytics hooks
25. Google Analytics - requires a Google Analytics property ID G-*
26. .gitignore installer - make sure that `site` and `.cache` are not in the main branch
27. extra CSS installer for iframe and customer prompt admonition
28. extra JavaScript installer - for prompt admonition copy button
29. Feature checklist - auto-detect and document which features are implemented
30. Learning mascot - add a pedagogical agent character to guide students
31. Instructor's guide - comprehensive teacher's guide with classroom tips
32. Custom 404 page - friendly error page with mascot image
33. Document status indicators - colored dots in nav showing page lifecycle state
34. Kanban board - GitHub Projects board for tracking textbook development
35. Mascot chapter updater - retrofit existing chapters with mascot admonitions
36. About page - professional about.md with motivation, author bio, and citations
37. Slide generator - install slide-viewer MicroSim and generate slides.md decks for chapters
38. Reading level analysis - Flesch-Kincaid grade level report for all chapters
39. Generate all supplementary content - glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, README
40. Book metrics report - chapters, concepts, glossary/FAQ counts, quiz & reference totals, diagrams, equations, MicroSims, word count & equivalent pages (book-metrics.md + chapter-metrics.md)
Type a number or feature name to install.
Note: If you see `navigation.tabs` in mkdocs.yml, remove it. These books
use side navigation optimized for wide landscape screens.
After displaying the list, wait for user to specify which feature they want.
Step 1b: Check for Navigation Tabs (Existing Projects)
When working with an existing mkdocs.yml, always check for and remove navigation tabs:
# REMOVE these lines if present in mkdocs.yml:
theme:
features:
- navigation.tabs # DELETE
- navigation.tabs.sticky # DELETE
These books use side navigation optimized for wide landscape screens. Top navigation tabs waste vertical space and are not appropriate for this format.
Step 2: Identify Installation Type
Match the user's request to the appropriate installation guide:
Routing Table
| Trigger Keywords |
Action |
Purpose |
| help, what can you do, features, capabilities, list features |
Display numbered list (Step 1) |
Show quick feature overview |
| init textbook, scaffold textbook, brand new book, empty directory, fresh start, new textbook from scratch, 0 |
references/init-textbook.md |
Bootstrap a brand-new textbook from scratch (mkdocs.yml + docs/ + license + contact + social-override hook) — run this before any other feature |
| 1, simple mkdocs, minimal template, starter config |
references/init-textbook.md |
Canonical scaffold (supersedes the old minimal template) |
| google analytics, GA4, measurement id, tracking id, G-, analytics property, register analytics, 25 |
references/google-analytics.md |
Create the GA4 property, write the G-* Measurement ID into mkdocs.yml extra.analytics, verify the tag, deploy |
| enrich, add feature, number 2-24, specific feature name |
references/mkdocs-features.md |
Install specific feature |
| new project, mkdocs, textbook, bootstrap, setup, template, new book |
references/init-textbook.md |
Create new MkDocs Material project (feature 0 scaffold) |
| graph viewer, learning graph, visualization, interactive graph, concept viewer |
references/learning-graph-viewer.md |
Add learning graph viewer to existing project |
| track skills, skill usage, activity tracking, hooks, usage analytics |
references/skill-tracker.md |
Set up skill tracking with hooks |
| generate cover image prompt, generate cover image, auto cover image prompt, create cover image promt, run cover prompt script |
references/cover-image-generator.md |
Generate a high-quality cover image prompt from the book's own content; image auto-generation via API/ChatGPT is optional and only runs if explicitly requested |
| cover image, home page, montage, book cover, index page |
references/home-page-template.md |
Create home page with cover image and social metadata |
| social media preview, social card, social meta, og:image, og:title, og:description, open graph, twitter card, twitter image, linkedin preview, slack unfurl, bk-check-social-cover, social hook, social override |
references/social-media-preview.md |
Install the Cairo-free hook that injects og:* and twitter:* meta tags on every page |
| logo, site logo, branding, upper left, header icon |
references/mkdocs-features.md |
Add custom logo with AI prompt examples |
| favicon, browser tab, bookmark icon, .ico |
references/mkdocs-features.md |
Add favicon with AI prompt examples |
| generate favicon, favicon from mascot, mascot favicon, favicon.ico from png, create favicon |
references/favicon-generator.md |
Generate favicon.ico from neutral.png mascot using Python |
| math, equations, latex, mathjax, katex |
references/mkdocs-features.md |
Add math equation support |
| feature checklist, generate feature checklist, feature status, what features |
references/feature-checklist-generator.md |
Auto-detect and document implemented features |
| quiz, quizzes, assessment, multiple choice |
references/mkdocs-features.md |
Add interactive quizzes |
| feedback, thumbs up, thumbs down, was this helpful |
references/mkdocs-features.md |
Add page feedback widget |
| comments, giscus, discussions |
references/mkdocs-features.md |
Add comment system |
| image zoom, lightbox, glightbox, click to enlarge |
references/mkdocs-features.md |
Add image zoom on click |
| code highlighting, syntax, copy button |
references/mkdocs-features.md |
Add code syntax highlighting |
| mermaid, diagrams, flowchart |
references/mkdocs-features.md |
Add Mermaid diagram support |
| admonition, callout, prompt box, copy prompt |
references/mkdocs-features.md |
Add custom admonitions with copy |
| mascot, learning mascot, pedagogical agent, character, guide character, persona |
references/learning-mascot.md |
Add a learning mascot to guide students |
| instructor guide, teacher guide, teachers guide, instructor's guide, classroom guide |
references/instructors-guide.md |
Generate comprehensive instructor's guide |
| 404, error page, not found, custom 404, page not found |
references/custom-404-page.md |
Add custom 404 page with mascot |
| document status, page status, status indicators, status dots, nav status, page lifecycle, review workflow |
references/document-status.md |
Add colored status dots to nav sidebar |
| kanban, project board, kanban board, project management, github project, task board, milestones, 34 |
references/kanban-board.md |
Create GitHub Projects Kanban board for textbook development |
| mascot chapter, update chapter, retrofit mascot, place mascot, add mascot to chapter, 35 |
references/mascot-chapter-updater.md |
Retrofit an existing chapter with mascot admonitions using placement rules |
| mascot placement rules, mascot rules, how often mascot, mascot frequency, which mascot pose, mascot admonition guidelines |
references/mascot-placement-rules.md |
Canonical single-source rules for when/how often each mascot pose is used (read, never restate) |
| about page, about, about.md, about this book, author bio, cite this book, citation, 36 |
references/about-page.md |
Generate professional about page with motivation, bio, and citations |
| slide generator, slides, slide deck, slide viewer, presentation, generate slides, install slide viewer, 37 |
references/slide-generator.md |
Install the slide-viewer MicroSim and generate slides.md decks for chapters |
| reading level, readability, flesch kincaid, grade level, reading analysis, 38 |
references/reading-level-analysis.md |
Analyze chapter reading level consistency |
| generate all supplementary content, supplementary content, complete the book, finish the book, book completion, generate glossary faq quiz, generate all content, all supplementary, 39 |
references/supplementary-content-generator.md |
Generate glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, and README in one coordinated workflow |
| book metrics, generate metrics, book-metrics, chapter metrics, content statistics, word count, page count, equivalent pages, book composition, metrics report, 40 |
references/book-metrics.md |
Generate book-metrics.md, chapter-metrics.md, and the metrics block in book-metadata.json via bk-generate-book-metrics |
Decision Tree
Asking for help or what book-installer can do?
→ YES: Display numbered list directly (Step 1)
Creating a new project/textbook from scratch (empty directory)?
→ YES: init-textbook.md (feature 0 — the canonical scaffold)
Registering the book with Google Analytics (GA4 / G-* Measurement ID)?
→ YES: google-analytics.md
Adding a learning graph viewer to existing project?
→ YES: learning-graph-viewer.md
Setting up skill usage tracking?
→ YES: skill-tracker.md
Want to GENERATE a high-quality cover image prompt from the book's content?
→ YES: cover-image-generator.md (prompt is the default output; auto-generation via API/ChatGPT only runs if explicitly requested)
Creating a cover image MANUALLY or setting up home page with social metadata?
→ YES: home-page-template.md
Installing the social media preview hook (og:* / twitter:* meta tags) or
fixing a failing bk-check-social-cover run?
→ YES: social-media-preview.md (Cairo-free; this is the default approach)
Want to generate a feature checklist showing what's implemented?
→ YES: feature-checklist-generator.md
Want to GENERATE a favicon.ico automatically from the mascot's neutral.png?
→ YES: favicon-generator.md (runs scripts/generate-favicon.py via Python/Pillow)
Want to add branding (logo, favicon, cover image)?
→ YES: mkdocs-features.md (Branding Features section)
Want to add a learning mascot (pedagogical agent) to guide students?
→ YES: learning-mascot.md
Want to generate an instructor's/teacher's guide?
→ YES: instructors-guide.md
Want a custom 404 error page with the mascot?
→ YES: custom-404-page.md
Want to add colored status dots to the nav sidebar for page lifecycle tracking?
→ YES: document-status.md
Want a GitHub Projects Kanban board to track textbook development?
→ YES: kanban-board.md
Want to retrofit an existing chapter with mascot admonitions?
→ YES: mascot-chapter-updater.md
Want to generate a professional about page with author bio and citations?
→ YES: about-page.md
Want to install a slide viewer and generate slide decks for chapters?
→ YES: slide-generator.md
Want to analyze reading level consistency across chapters?
→ YES: reading-level-analysis.md
Want to generate all supplementary content in one pass (glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, README)?
→ YES: supplementary-content-generator.md
Want to generate book metrics only (chapters, concepts, word/page counts,
diagram/MicroSim/quiz totals) into book-metrics.md and chapter-metrics.md?
→ YES: book-metrics.md
Want to add a specific feature (equations, quizzes, feedback, etc.)?
→ YES: mkdocs-features.md (then follow specific feature instructions)
Step 2: Load the Matched Guide
Read the corresponding guide file from references/ and follow its installation workflow.
Step 3: Execute Installation
Each guide contains:
- Prerequisites and requirements
- Step-by-step installation commands
- Configuration options
- Verification steps
- Troubleshooting tips
Available Installation Guides
mkdocs-features.md
Purpose: Detailed configuration for all MkDocs feature enhancements
Contains: Full configuration snippets for features 2-24 listed in the help output, including:
- YAML for mkdocs.yml
- JavaScript files to create
- CSS files to create
- Usage examples
Use when:
- User selects a feature by number or name
- User wants detailed configuration for a specific feature
- User has a minimal mkdocs.yml and wants to enrich it
init-textbook.md (feature 0)
Purpose: The canonical scaffold for a brand-new intelligent textbook in an empty directory
Creates:
- mkdocs.yml (side nav, search, admonitions, arithmatex, exclude_docs, schema URI)
- docs/ tree: index, about, course-description, contact, license, chapters/, learning-graph/, sims/, css/extra.css, img/ (cover + license badge)
- CONTENT-GENERATION-GUIDE.md (CIS-driven word-count targets, anti-padding rules, MicroSim and Markdown rules — read by book-chapter-generator and chapter-content-generator)
- plugins/social_override.py hook (per-page og:/twitter: image override)
- .gitignore and VS Code workspace file
- MicroSim status-indicator plumbing (scaffold/built/approved)
Templates: single canonical copy in assets/init-textbook/
Prerequisites:
- Empty (or nearly empty) project directory — refuses to overwrite mkdocs.yml, docs/index.md, or docs/license.md
google-analytics.md (feature 25)
Purpose: Register the book as a Google Analytics 4 property and wire the Measurement ID into mkdocs.yml
Creates:
- GA4 property + web data stream (via Claude in Chrome)
extra.analytics block in mkdocs.yml with the G-* Measurement ID
- Build-time tag verification, commit, and gh-deploy
Prerequisites:
- Claude in Chrome extension connected; user logged into Google Analytics
- site_url set in mkdocs.yml
learning-graph-viewer.md
Purpose: Add interactive learning graph exploration to existing textbook
Creates:
- Interactive vis-network graph viewer
- Search, filtering, and statistics features
- Integration with existing learning-graph.json
Prerequisites:
- Existing MkDocs project
- learning-graph.json file present
skill-tracker.md
Purpose: Set up Claude Code skill usage tracking
Creates:
- Hook scripts for tracking skill invocations
- Activity log directory structure
- Reporting scripts for usage analysis
Prerequisites:
- Claude Code installed
- ~/.claude directory exists
social-media-preview.md
Purpose: Install a Cairo-free MkDocs hook that emits Open Graph and Twitter Card meta tags on every page
Creates:
plugins/social_override.py — on_post_page hook that injects/replaces og:title, og:description, og:image, og:type, og:url, and twitter:* tags
hooks: block in mkdocs.yml referencing the new file
Features:
- Reads
image:, title:, description: from each page's frontmatter; falls back to img/cover.png and the site-wide values
- Emits absolute
og:image URLs by joining site_url with the image path (so crawlers and bk-check-social-cover can HEAD-request them)
- Works without
mkdocs-material[imaging] / Cairo — the common-case default
- Compatible with the full
social plugin when Cairo is present: replaces its auto-generated /assets/images/social/... URLs with the declared cover.png
- Verified via
~/.local/bin/bk-check-social-cover (which enforces og:image basename = cover.png and image reachability)
Prerequisites:
- Existing MkDocs Material project with
site_url: set
docs/img/cover.png (use cover-image-generator.md or home-page-template.md first if missing)
- Home page frontmatter with
title: and description: (typically from home-page-template.md)
home-page-template.md
Purpose: Create professional home page with cover image and social media optimization
Creates:
- docs/index.md with proper frontmatter metadata
- AI image generation prompts for cover with montage background
- Open Graph and Twitter Card configuration
Features:
- Cover image design guidance (1.91:1 aspect ratio)
- Montage element suggestions by topic
- Social media preview optimization
- Example prompts for various book themes
Prerequisites:
- Existing MkDocs project
- Access to AI image generator (DALL-E, Midjourney, etc.)
learning-mascot.md
Purpose: Design and implement a pedagogical agent (learning mascot) that guides students through the textbook
Creates:
- Character design (name, species, appearance, personality, catchphrase)
- AI image generation prompts for consistent mascot poses
- Implementation via inline images, custom CSS admonitions, or JavaScript auto-detection
- A mascot test page with automated transparency/4 px trim checks and all seven admonition previews
- CONTENT-GENERATION-GUIDE.md character guidelines for consistent AI-generated content, with the placement rules rendered from
references/mascot-placement-rules.md
Features:
- Subject-specific mascot suggestions with reasoning
- Seven standard pose variants (neutral, welcome, thinking, tip, warning, encouraging, celebration)
- Three implementation methods at different complexity levels
- Restraint guidelines to prevent overuse
Prerequisites:
- Existing MkDocs Material project
- Access to AI image generator (DALL-E, Midjourney, etc.)
instructors-guide.md
Purpose: Generate a comprehensive instructor's/teacher's guide for the textbook
Creates:
docs/teachers-guide/index.md (or docs/instructors-guide/index.md for college-level)
- Navigation entry in mkdocs.yml
Features:
- Five levels of intelligent textbooks explained
- Detailed usage instructions for chapters, MicroSims, glossary, FAQ, quizzes, and references
- Classroom tips (before/during/after class suggestions, pacing)
- MicroSim iframe embedding guide for external LMS pages
- Creative Commons license explained in plain English (what you can/cannot do)
- Step-by-step customization guide (fork, clone, change colors/title/logo, deploy)
- Google Analytics setup instructions
- xAPI/LRS overview with FERPA/COPPA/GDPR regulatory warnings
- Learning graph usage tips for teachers
- Pedagogical agent (mascot) documentation (if mascot exists)
- All technical terms defined before use — no assumed prior knowledge
Prerequisites:
- Existing MkDocs Material project
- At least some chapter content written
custom-404-page.md
Purpose: Add a custom 404 error page featuring the project's learning mascot
Creates:
overrides/404.html — Jinja2 template extending Material base theme with mascot image, friendly message, and home link
- mkdocs.yml updates for
custom_dir and static_templates
Features:
- Uses the mascot's warning pose (or other pose) centered on the page
- Inherits full site navigation (header, sidebar, footer) from the Material theme
- Customizable message matched to the mascot's personality and voice
- Absolute image paths so the 404 works from any URL depth
Prerequisites:
- Existing MkDocs Material project
- Learning mascot images in
docs/img/mascot/ (use learning-mascot.md first if needed)
document-status.md
Purpose: Add per-page colored status dots to the navigation sidebar for tracking page lifecycle state
Creates:
extra.status configuration in mkdocs.yml
- CSS rules for colored status dots in extra.css
status: frontmatter on individual pages
Features:
- Three-state workflow (spec-complete → prototype → ready-for-testing)
- Colored dots (red, orange, green) visible in the nav sidebar
- Tooltip text on hover
- Customizable status codes for any workflow
Prerequisites:
- Existing MkDocs Material project
- Custom CSS file referenced in
extra_css
reading-level-analysis.md
Purpose: Analyze Flesch-Kincaid grade level consistency across all chapters
Creates:
docs/learning-graph/chapter-reading-levels.md — per-chapter reading level report
Uses script: scripts/analyze-reading-levels.py
Features:
- Strips markdown/HTML formatting to analyze pure prose
- Per-chapter table with FK grade and explanatory notes
- Summary statistics (mean, median, range, standard deviation)
- Interpretation section explaining whether variation is meaningful
- Identifies vocabulary-driven score inflation vs. genuine difficulty differences
Prerequisites:
- Existing MkDocs project with chapters in
docs/chapters/
- Python
textstat library (pip install textstat)
book-metrics.md
Purpose: Generate comprehensive book-wide and per-chapter metrics for an intelligent textbook
Creates:
docs/learning-graph/book-metrics.md — Book Composition + Student-Facing Content Metrics tables
docs/learning-graph/chapter-metrics.md — per-chapter breakdown
- merges a
metrics block of book-wide totals into docs/learning-graph/book-metadata.json (author fields preserved)
Uses script: bk-generate-book-metrics (resolves $BK_HOME/src/book-metrics/book-metrics.py); fallback python3 "$BK_HOME/src/book-metrics/book-metrics.py" docs
Features:
- Tracks all 12 book-composition elements with Required/Recommended/Optional status
- Counts concepts, chapters, MicroSims, stories, glossary terms, FAQs, quiz questions, references, diagrams, equations, words, links, appendices, mascot poses
- Estimates equivalent printed pages and records the development stage
- Produces the totals the intelligent-textbooks case-studies index displays
Prerequisites:
- Existing MkDocs project with chapters in
docs/chapters/
$BK_HOME exported and bk-generate-book-metrics on $PATH
favicon-generator.md
Purpose: Generate a web-compliant multi-resolution favicon.ico from the mascot's neutral.png
Creates:
docs/img/favicon.ico — multi-resolution icon (16, 32, 48, 64, 128, 256 px) embedded in a single .ico file
Uses script: scripts/generate-favicon.py
How it works:
- Detects the bounding box of non-transparent pixels (trims invisible padding)
- Centers the visible content on a square canvas with configurable padding
- Downscales to each favicon size using Lanczos resampling
- Supports transparent or white background canvas
Prerequisites:
- Mascot image at
docs/img/mascot/neutral.png (image need not be square)
- Python
Pillow library (pip install Pillow)
cover-image-generator.md
Purpose: Craft a high-quality cover image prompt at docs/img/cover-image-prompt.md, built from the book's title, course description, concept list, mascot, and MicroSim screenshots. Image auto-generation is optional and only runs if the user explicitly asks for it.
Provides:
- Guidance for selecting 6-10 montage concepts from the book's own content
- A detailed prompt template covering subject/tone, title typography, montage, mascot, style/color, and things to avoid
- Recommended manual review loop: paste the prompt into a text-to-image tool, compare drafts, iterate on the prompt before finalizing
- Optional automated paths (API, browser automation, or local-prompt) with troubleshooting — only used on explicit request
Prerequisites:
- Existing MkDocs project with mkdocs.yml
- docs/course-description.md with book content description
- Only if auto-generation is requested: OpenAI API billing, ChatGPT Pro subscription, or a free AI image generator
kanban-board.md
Purpose: Create a GitHub Projects (v2) Kanban board for tracking textbook development progress
Creates:
- GitHub Projects board with Board (Kanban) layout
- Priority field (High / Medium / Low)
- 13 standard textbook milestone draft items
docs/project-management.md with column documentation and workflow guide
- README section about the Kanban board
Features:
- Automated setup via
gh project CLI commands
- Links project to the repository automatically
- Pre-populated milestones matching the 12-step textbook workflow
- Fallback instructions for manual setup if
gh commands fail
Prerequisites:
gh CLI installed and authenticated
project scope on the GitHub token (gh auth refresh -s project)
- Existing MkDocs project with mkdocs.yml
supplementary-content-generator.md
Purpose: Generate all standard supplementary content for an intelligent textbook in a single coordinated workflow
Produces (in execution order):
docs/about.md — professional about page (via about-page.md reference)
docs/glossary.md — ISO 11179-compliant glossary (via glossary-generator skill)
docs/faq.md — ≥ 30-question FAQ (via faq-generator skill)
docs/chapters/*/quiz.md — per-chapter quizzes (via quiz-generator skill)
docs/chapters/*/references.md — per-chapter reference lists (via reference-generator skill)
docs/img/cover.png — book cover image + social-preview hook (via cover-image-generator.md + social-media-preview.md)
- Book metrics report (via
bk-generate-book-metrics script)
- Diagram reports (via
bk-diagram-reports script)
README.md — GitHub-facing README after metrics, so it can embed content counts (via the book-publisher readme route — skill)
docs/index.md — main landing page last, so it can link to all of the above (via home-page-template.md)
- Updated
mkdocs.yml nav entries for all generated files
Execution order: about → glossary → FAQ → quizzes → references → cover image → metrics → diagram reports → README → landing page → nav update → verification
Model guidance: All text-generation steps use Sonnet. Any MicroSim created during this workflow must use claude-opus-4-7 with high thinking — Opus is significantly better at the coding and spatial reasoning MicroSims require.
Prerequisites:
- Existing MkDocs project with
mkdocs.yml
docs/course-description.md present
docs/learning-graph/learning-graph.json present
- At least one chapter under
docs/chapters/
slide-generator.md
Purpose: Install the slide-viewer MicroSim into an intelligent textbook project and generate presentation-style slides.md decks for specified chapters
Creates:
docs/sims/slide-viewer/ — viewer shell (main.html, script.js, local.css, index.md) that fetches any rendered MkDocs page URL, splits its content on <hr> elements, and renders one slide at a time with keyboard + button navigation
docs/chapters/<slug>/slides.md — per chapter: title slide, content slides separated by ---, retrieval check, bridge, celebration close
- Three-button nav bar (
Content, Slides, Slides in Viewer) at the top of each chapter's index.md and its slides.md
- mkdocs.yml nav restructured so each chapter with slides has
Content / Slides sub-entries
Features:
- Viewer reads MkDocs' rendered HTML (never raw
.md — MkDocs doesn't serve .md directly)
- Mascot integration: neutral pose on every slide, celebration pose on the last slide (uses
docs/img/mascot/neutral.png and celebration.png if present; silently absent otherwise)
- First/last-slide jump buttons,
Home/End keys, fullscreen, table-of-contents overlay
- Distills chapter
index.md into 15–28 slides following project voice/style rules
Prerequisites:
- Existing MkDocs Material project with
docs/chapters/ populated
- Chapter
index.md files with real content (not just scaffold) — guide checks line counts before generating
- Optional: mascot installed via
learning-mascot.md
mascot-placement-rules.md
Purpose: The single source of truth for when a learning mascot may appear, how often, and which pose carries which pedagogical job
Used by: learning-mascot.md, mascot-chapter-updater.md, instructors-guide.md, and the chapter-content-generator skill — all of which reference this file rather than restating its rules
Contains:
- The admonition format and the Markdown-vs-raw-HTML image path rules
- The placement table (context → pose → per-chapter count)
- Hard limits: fewer than 10 admonitions per chapter, no back-to-back placement, one welcome and one celebration, 1-3 sentence bodies
- Per-pose instructional-design rules for all seven poses
- The one-time Chapter 1 self-introduction pattern
- The post-generation validation rule
Important: never copy this file's tables or counts into another skill or into a book by hand. Skills reference it by path; books receive a rendered copy via scripts/render-mascot-guide.py, spliced between sentinel comments so it can be regenerated. Run scripts/bk-check-mascot-rules from the repo root to verify no restatement has crept back in.
mascot-chapter-updater.md
Purpose: Retrofit an existing chapter markdown file with mascot admonitions in the right places, following the canonical references/mascot-placement-rules.md
Creates:
- In-place edits to the specified chapter file only (no new files)
- A placement plan shown to the user for confirmation before editing
Features:
- LLM-driven workflow for semantic placement (no regex auto-insertion)
- Enforces the hard limits defined in
references/mascot-placement-rules.md (total ceiling, one welcome and one celebration maximum, no back-to-back placements)
- Image-path guidance for directory-URL rendering (counts
../ from rendered page)
- Voice and body-text rules: 1-3 sentences, in-character, specific to chapter content
- Validation via
scripts/validate-chapter-mascots.py that flags count limits, back-to-backs, missing mascot images, and body-text length
Prerequisites:
- Mascot images present in
docs/img/mascot/ or docs/img/mascots/
docs/css/mascot.css loaded and the mascot-test page renders correctly
- Specific chapter file identified by absolute path
Examples
Example 1: Ask for Help
User: "book-installer help"
Routing: Keyword "help" → Display numbered list
Action: Show the numbered feature list (Step 1), then wait for user to select a feature
Example 2: Add a Specific Feature
User: "Add math equation support to my book"
Routing: Keyword "math" → references/mkdocs-features.md
Action: Load mkdocs-features.md, find the Math Equations section, and apply the configuration
Example 2b: Select by Number
User: "5"
Routing: Number selection after help list → references/mkdocs-features.md
Action: Load mkdocs-features.md, find Math Equations (item 5), and apply the configuration
Example 2c: Simple Template
User: "1"
Routing: Number 1 → references/init-textbook.md (canonical scaffold)
Action: Load init-textbook.md and scaffold the starter config and docs/ tree
Example 3: New Textbook Project
User: "I want to create a new intelligent textbook about machine learning" (empty directory)
Routing: Keywords "create", "new", "textbook" → references/init-textbook.md
Action: Read init-textbook.md, gather SITE_NAME/SITE_DESCRIPTION, confirm the substitution table, scaffold from assets/init-textbook/
Example 3b: Register Google Analytics
User: "Add Google Analytics to this book" or "25"
Routing: Keywords "google analytics", "GA4", "25" → references/google-analytics.md
Action: Read google-analytics.md; create the GA4 property, write the G-* ID into mkdocs.yml extra.analytics, verify the tag, deploy
Example 4: Add Graph Viewer
User: "Add an interactive viewer for the learning graph"
Routing: Keywords "viewer", "learning graph", "interactive" → references/learning-graph-viewer.md
Action: Read learning-graph-viewer.md and follow its workflow
Example 5: Track Skill Usage
User: "I want to track which skills I use most often"
Routing: Keywords "track", "skills", "usage" → references/skill-tracker.md
Action: Read skill-tracker.md and follow its workflow
Example 6: Create Cover Image
User: "Help me create a cover image for my textbook"
Routing: Keywords "cover image", "textbook" → references/home-page-template.md
Action: Read home-page-template.md and follow its workflow
Example 7: Set Up Home Page with Social Sharing
User: "I need to add og:image metadata to my home page"
Routing: Keywords "og:image", "home page" → references/home-page-template.md
Action: Read home-page-template.md and follow its workflow
Example 8: Generate Cover Image Prompt
User: "generate cover image" or "book-installer generate cover image"
Routing: Keywords "generate cover image" → references/cover-image-generator.md
Action: Read cover-image-generator.md, gather source material (title, course description, concept list, mascot, MicroSim screenshots), write docs/img/cover-image-prompt.md, and recommend the user paste it into a text-to-image tool and review drafts. Only ask about API key/ChatGPT Pro/macOS and run generate-cover.sh if the user explicitly requests auto-generation.
Example 9: Add a Learning Mascot
User: "I want to add a mascot character to my math textbook"
Routing: Keywords "mascot", "character" → references/learning-mascot.md
Action: Read learning-mascot.md, guide user through character design, generate AI image prompts, and implement chosen method (inline, CSS admonitions, or JS detection)
Example 10: Generate Feature Checklist
User: "generate a feature checklist" or "what features do I have"
Routing: Keywords "feature checklist" → references/feature-checklist-generator.md
Action: Read feature-checklist-generator.md, run the detection script, generate docs/feature-checklist.md with detected statuses
Example 11: Generate Instructor's Guide
User: "add a teacher's guide" or "create instructor guide"
Routing: Keywords "teacher guide", "instructor guide" → references/instructors-guide.md
Action: Read instructors-guide.md, gather project variables from mkdocs.yml/course-description.md/CLAUDE.md, generate the guide with all variables substituted, add to navigation
Example 12: Create Kanban Board
User: "set up a kanban board for my textbook" or "create a project board"
Routing: Keywords "kanban", "project board" → references/kanban-board.md
Action: Read kanban-board.md, verify gh auth with project scope, create the GitHub Project, link to repo, populate milestones, create docs/project-management.md, update nav and README
Example 13: Generate About Page
User: "create an about page" or "add about.md with author bio and citations"
Routing: Keywords "about page", "about", "author bio", "citation" → references/about-page.md
Action: Read about-page.md, gather project variables from mkdocs.yml/course-description.md, generate docs/about.md with all sections (motivation, author bio, citation formats), add to navigation
Example 14: Add Mascots to an Existing Chapter
User: "add Sparky admonitions to chapter 2" or "place the mascot in docs/chapters/02-ohms-law/index.md"
Routing: Keywords "mascot chapter", "place mascot", "add mascot to chapter" → references/mascot-chapter-updater.md
Action: Read mascot-chapter-updater.md, survey the chapter, propose a placement plan with line numbers, wait for user confirmation, apply edits, run validate-chapter-mascots.py, and address any flags
Example 15: Generate Favicon from Mascot
User: "generate favicon from mascot" or "create favicon.ico from neutral.png"
Routing: Keywords "generate favicon", "mascot favicon", "favicon from mascot" → references/favicon-generator.md
Action: Read favicon-generator.md, verify docs/img/mascot/neutral.png exists and Pillow is installed, run scripts/generate-favicon.py from the project root, then update theme.favicon in mkdocs.yml to img/favicon.ico
Example 15b: Install Social Media Preview Hook
User: "add the social media preview mkdocs hook" or "my bk-check-social-cover is failing" or "install og:image meta tags"
Routing: Keywords "social media preview", "og:image", "bk-check-social-cover", "social hook" → references/social-media-preview.md
Action: Read social-media-preview.md, create plugins/social_override.py at the project root with the exact code in the reference, add a top-level hooks: - plugins/social_override.py block to mkdocs.yml, run mkdocs build, verify the nine og:* / twitter:* meta tags appear in site/index.html, then run bk-check-social-cover against either the deployed URL or a local server staging the build under /<project>/
Example 17: Generate All Supplementary Content
User: "generate all supplementary content" or "complete the book" or "39"
Routing: Keywords "supplementary content", "complete the book", "39" → references/supplementary-content-generator.md
Action: Read supplementary-content-generator.md. First inventory existing files. Then execute Steps 2–12 in order: generate about page, landing pag
…(truncated)
1---2name: book-installer3description: Installs and configures intelligent-textbook infrastructure - scaffold a brand-new MkDocs Material textbook (init textbook), install any of 40 features (math, mascot, learning graph viewer, Google Analytics GA4, custom 404, kanban board), and generate book metrics. Routes to the appropriate installation guide.4license: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0)5metadata:6 source: https://skillmd.com/skills/dmccreary/book-installer7 ibook.version: "1.0"8---910# Book Installer1112**Version:** 1.01314### Changelog1516- **v1.0** — First tracked version number for this skill. Adds17 `references/mascot-placement-rules.md` as the single canonical source for when18 and how often a learning mascot may appear, plus19 `scripts/render-mascot-guide.py` (renders those rules into a book's20 `CONTENT-GENERATION-GUIDE.md` between sentinel comments so the copy is21 regenerated, never hand-edited). The per-chapter ceiling is raised from 6 to 922 admonitions for longer chapters, and `scripts/validate-chapter-mascots.py` now23 reports the deprecated `-encouraging` spelling of the encourage pose class —24 which `mascot.css` never defined, so it rendered unstyled — and exempts the25 Chapter 1 self-introduction26 from the 1-3 sentence cap it always violated. Version is tracked under27 `metadata:` rather than a bare `version:` key, which strict packaging28 validation rejects.2930## Overview3132This meta-skill handles installation and setup tasks for intelligent textbook projects. It consolidates five installation skills into a single entry point with on-demand loading of specific installation guides.3334## When to Use This Skill3536Use this skill when users request:3738- Setting up a new MkDocs Material project39- Creating a new intelligent textbook from scratch (feature #0 scaffold)40- Installing a learning graph viewer41- Setting up skill usage tracking with hooks42- Registering the book with Google Analytics (GA4 Measurement ID)43- Bootstrapping project infrastructure4445## Step 1: Handle Help Requests4647If the user asks for "help", "what can you do", or "list features", display this numbered list directly (do not load a reference file):4849```50Book Installer Features (most → least common):5152 0. New textbook scaffold - complete mkdocs.yml + docs/ tree + license for an empty directory (run once at project birth)53 1. Simple mkdocs.yml template - Minimal starter config for new projects (see feature 0)54 2. Site logo - Add custom logo to header55 3. Favicon - Browser tab/bookmark icon56 3b. Generate favicon from mascot - Auto-generate favicon.ico from neutral.png mascot image57 4. Cover image & social preview - Home page image + og:image metadata58 4b. Generate cover image prompt - Create a prompt for generating a cover image using text-to-image AI (DALL-E, Midjourney, etc.)59 4c. Social media preview hook - Inject og:* / twitter:* meta tags via MkDocs hook (no Cairo required)60 5. Math equations - KaTeX (recommended) or MathJax61 6. Code syntax highlighting - Language-aware code blocks62 7. Code copy button - One-click copy for code blocks63 8. Mermaid diagrams - Flowcharts, sequence diagrams from text64 9. Content tabs - Tabbed sections for alternatives6510. Image zoom (GLightbox) - Click to enlarge images6611. Custom admonitions - Prompt boxes with copy button6712. Interactive quizzes - Self-assessment questions6813. Abbreviations & tooltips - Glossary hover definitions6914. Task lists - Checkbox lists7015. Simple feedback - Thumbs up/down per page7116. Detailed comments (Giscus) - GitHub Discussions integration7217. Tags & categorization - Page tagging system7318. Search enhancements - Suggestions and highlighting7419. Table of contents config - TOC sidebar options7520. Blog support - Add blog section7621. Announcement bar - Dismissible top banner7722. Privacy & cookie consent - GDPR compliance7823. Learning graph viewer - Interactive concept visualization7924. Skill usage tracker - Claude Code analytics hooks8025. Google Analytics - requires a Google Analytics property ID G-*8126. .gitignore installer - make sure that `site` and `.cache` are not in the main branch8227. extra CSS installer for iframe and customer prompt admonition8328. extra JavaScript installer - for prompt admonition copy button8429. Feature checklist - auto-detect and document which features are implemented8530. Learning mascot - add a pedagogical agent character to guide students8631. Instructor's guide - comprehensive teacher's guide with classroom tips8732. Custom 404 page - friendly error page with mascot image8833. Document status indicators - colored dots in nav showing page lifecycle state8934. Kanban board - GitHub Projects board for tracking textbook development9035. Mascot chapter updater - retrofit existing chapters with mascot admonitions9136. About page - professional about.md with motivation, author bio, and citations9237. Slide generator - install slide-viewer MicroSim and generate slides.md decks for chapters9338. Reading level analysis - Flesch-Kincaid grade level report for all chapters9439. Generate all supplementary content - glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, README9540. Book metrics report - chapters, concepts, glossary/FAQ counts, quiz & reference totals, diagrams, equations, MicroSims, word count & equivalent pages (book-metrics.md + chapter-metrics.md)9697Type a number or feature name to install.9899Note: If you see `navigation.tabs` in mkdocs.yml, remove it. These books100use side navigation optimized for wide landscape screens.101```102103After displaying the list, wait for user to specify which feature they want.104105---106107## Step 1b: Check for Navigation Tabs (Existing Projects)108109When working with an existing mkdocs.yml, always check for and remove navigation tabs:110111```yaml112# REMOVE these lines if present in mkdocs.yml:113theme:114 features:115 - navigation.tabs # DELETE116 - navigation.tabs.sticky # DELETE117```118119These books use side navigation optimized for wide landscape screens. Top navigation tabs waste vertical space and are not appropriate for this format.120121---122123## Step 2: Identify Installation Type124125Match the user's request to the appropriate installation guide:126127### Routing Table128129| Trigger Keywords | Action | Purpose |130|------------------|--------|---------|131| help, what can you do, features, capabilities, list features | Display numbered list (Step 1) | Show quick feature overview |132| init textbook, scaffold textbook, brand new book, empty directory, fresh start, new textbook from scratch, 0 | `references/init-textbook.md` | Bootstrap a brand-new textbook from scratch (mkdocs.yml + docs/ + license + contact + social-override hook) — run this *before* any other feature |133| 1, simple mkdocs, minimal template, starter config | `references/init-textbook.md` | Canonical scaffold (supersedes the old minimal template) |134| google analytics, GA4, measurement id, tracking id, G-, analytics property, register analytics, 25 | `references/google-analytics.md` | Create the GA4 property, write the G-* Measurement ID into mkdocs.yml extra.analytics, verify the tag, deploy |135| enrich, add feature, number 2-24, specific feature name | `references/mkdocs-features.md` | Install specific feature |136| new project, mkdocs, textbook, bootstrap, setup, template, new book | `references/init-textbook.md` | Create new MkDocs Material project (feature 0 scaffold) |137| graph viewer, learning graph, visualization, interactive graph, concept viewer | `references/learning-graph-viewer.md` | Add learning graph viewer to existing project |138| track skills, skill usage, activity tracking, hooks, usage analytics | `references/skill-tracker.md` | Set up skill tracking with hooks |139| generate cover image prompt, generate cover image, auto cover image prompt, create cover image promt, run cover prompt script | `references/cover-image-generator.md` | Generate a high-quality cover image prompt from the book's own content; image auto-generation via API/ChatGPT is optional and only runs if explicitly requested |140| cover image, home page, montage, book cover, index page | `references/home-page-template.md` | Create home page with cover image and social metadata |141| social media preview, social card, social meta, og:image, og:title, og:description, open graph, twitter card, twitter image, linkedin preview, slack unfurl, bk-check-social-cover, social hook, social override | `references/social-media-preview.md` | Install the Cairo-free hook that injects og:* and twitter:* meta tags on every page |142| logo, site logo, branding, upper left, header icon | `references/mkdocs-features.md` | Add custom logo with AI prompt examples |143| favicon, browser tab, bookmark icon, .ico | `references/mkdocs-features.md` | Add favicon with AI prompt examples |144| generate favicon, favicon from mascot, mascot favicon, favicon.ico from png, create favicon | `references/favicon-generator.md` | Generate favicon.ico from neutral.png mascot using Python |145| math, equations, latex, mathjax, katex | `references/mkdocs-features.md` | Add math equation support |146| feature checklist, generate feature checklist, feature status, what features | `references/feature-checklist-generator.md` | Auto-detect and document implemented features |147| quiz, quizzes, assessment, multiple choice | `references/mkdocs-features.md` | Add interactive quizzes |148| feedback, thumbs up, thumbs down, was this helpful | `references/mkdocs-features.md` | Add page feedback widget |149| comments, giscus, discussions | `references/mkdocs-features.md` | Add comment system |150| image zoom, lightbox, glightbox, click to enlarge | `references/mkdocs-features.md` | Add image zoom on click |151| code highlighting, syntax, copy button | `references/mkdocs-features.md` | Add code syntax highlighting |152| mermaid, diagrams, flowchart | `references/mkdocs-features.md` | Add Mermaid diagram support |153| admonition, callout, prompt box, copy prompt | `references/mkdocs-features.md` | Add custom admonitions with copy |154| mascot, learning mascot, pedagogical agent, character, guide character, persona | `references/learning-mascot.md` | Add a learning mascot to guide students |155| instructor guide, teacher guide, teachers guide, instructor's guide, classroom guide | `references/instructors-guide.md` | Generate comprehensive instructor's guide |156| 404, error page, not found, custom 404, page not found | `references/custom-404-page.md` | Add custom 404 page with mascot |157| document status, page status, status indicators, status dots, nav status, page lifecycle, review workflow | `references/document-status.md` | Add colored status dots to nav sidebar |158| kanban, project board, kanban board, project management, github project, task board, milestones, 34 | `references/kanban-board.md` | Create GitHub Projects Kanban board for textbook development |159| mascot chapter, update chapter, retrofit mascot, place mascot, add mascot to chapter, 35 | `references/mascot-chapter-updater.md` | Retrofit an existing chapter with mascot admonitions using placement rules |160| mascot placement rules, mascot rules, how often mascot, mascot frequency, which mascot pose, mascot admonition guidelines | `references/mascot-placement-rules.md` | **Canonical** single-source rules for when/how often each mascot pose is used (read, never restate) |161| about page, about, about.md, about this book, author bio, cite this book, citation, 36 | `references/about-page.md` | Generate professional about page with motivation, bio, and citations |162| slide generator, slides, slide deck, slide viewer, presentation, generate slides, install slide viewer, 37 | `references/slide-generator.md` | Install the slide-viewer MicroSim and generate slides.md decks for chapters |163| reading level, readability, flesch kincaid, grade level, reading analysis, 38 | `references/reading-level-analysis.md` | Analyze chapter reading level consistency |164| generate all supplementary content, supplementary content, complete the book, finish the book, book completion, generate glossary faq quiz, generate all content, all supplementary, 39 | `references/supplementary-content-generator.md` | Generate glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, and README in one coordinated workflow |165| book metrics, generate metrics, book-metrics, chapter metrics, content statistics, word count, page count, equivalent pages, book composition, metrics report, 40 | `references/book-metrics.md` | Generate book-metrics.md, chapter-metrics.md, and the metrics block in book-metadata.json via bk-generate-book-metrics |166167### Decision Tree168169```170Asking for help or what book-installer can do?171 → YES: Display numbered list directly (Step 1)172173Creating a new project/textbook from scratch (empty directory)?174 → YES: init-textbook.md (feature 0 — the canonical scaffold)175176Registering the book with Google Analytics (GA4 / G-* Measurement ID)?177 → YES: google-analytics.md178179Adding a learning graph viewer to existing project?180 → YES: learning-graph-viewer.md181182Setting up skill usage tracking?183 → YES: skill-tracker.md184185Want to GENERATE a high-quality cover image prompt from the book's content?186 → YES: cover-image-generator.md (prompt is the default output; auto-generation via API/ChatGPT only runs if explicitly requested)187188Creating a cover image MANUALLY or setting up home page with social metadata?189 → YES: home-page-template.md190191Installing the social media preview hook (og:* / twitter:* meta tags) or192fixing a failing bk-check-social-cover run?193 → YES: social-media-preview.md (Cairo-free; this is the default approach)194195Want to generate a feature checklist showing what's implemented?196 → YES: feature-checklist-generator.md197198Want to GENERATE a favicon.ico automatically from the mascot's neutral.png?199 → YES: favicon-generator.md (runs scripts/generate-favicon.py via Python/Pillow)200201Want to add branding (logo, favicon, cover image)?202 → YES: mkdocs-features.md (Branding Features section)203204Want to add a learning mascot (pedagogical agent) to guide students?205 → YES: learning-mascot.md206207Want to generate an instructor's/teacher's guide?208 → YES: instructors-guide.md209210Want a custom 404 error page with the mascot?211 → YES: custom-404-page.md212213Want to add colored status dots to the nav sidebar for page lifecycle tracking?214 → YES: document-status.md215216Want a GitHub Projects Kanban board to track textbook development?217 → YES: kanban-board.md218219Want to retrofit an existing chapter with mascot admonitions?220 → YES: mascot-chapter-updater.md221222Want to generate a professional about page with author bio and citations?223 → YES: about-page.md224225Want to install a slide viewer and generate slide decks for chapters?226 → YES: slide-generator.md227228Want to analyze reading level consistency across chapters?229 → YES: reading-level-analysis.md230231Want to generate all supplementary content in one pass (glossary, FAQ, per-chapter quizzes & references, book metrics, diagram reports, about page, landing page, README)?232 → YES: supplementary-content-generator.md233234Want to generate book metrics only (chapters, concepts, word/page counts,235diagram/MicroSim/quiz totals) into book-metrics.md and chapter-metrics.md?236 → YES: book-metrics.md237238Want to add a specific feature (equations, quizzes, feedback, etc.)?239 → YES: mkdocs-features.md (then follow specific feature instructions)240```241242## Step 2: Load the Matched Guide243244Read the corresponding guide file from `references/` and follow its installation workflow.245246## Step 3: Execute Installation247248Each guide contains:2491. Prerequisites and requirements2502. Step-by-step installation commands2513. Configuration options2524. Verification steps2535. Troubleshooting tips254255## Available Installation Guides256257### mkdocs-features.md258259**Purpose:** Detailed configuration for all MkDocs feature enhancements260261**Contains:** Full configuration snippets for features 2-24 listed in the help output, including:262- YAML for mkdocs.yml263- JavaScript files to create264- CSS files to create265- Usage examples266267**Use when:**268- User selects a feature by number or name269- User wants detailed configuration for a specific feature270- User has a minimal mkdocs.yml and wants to enrich it271272### init-textbook.md (feature 0)273274**Purpose:** The canonical scaffold for a brand-new intelligent textbook in an empty directory275276**Creates:**277- mkdocs.yml (side nav, search, admonitions, arithmatex, exclude_docs, schema URI)278- docs/ tree: index, about, course-description, contact, license, chapters/, learning-graph/, sims/, css/extra.css, img/ (cover + license badge)279- CONTENT-GENERATION-GUIDE.md (CIS-driven word-count targets, anti-padding rules, MicroSim and Markdown rules — read by book-chapter-generator and chapter-content-generator)280- plugins/social_override.py hook (per-page og:/twitter: image override)281- .gitignore and VS Code workspace file282- MicroSim status-indicator plumbing (scaffold/built/approved)283284**Templates:** single canonical copy in `assets/init-textbook/`285286**Prerequisites:**287- Empty (or nearly empty) project directory — refuses to overwrite mkdocs.yml, docs/index.md, or docs/license.md288289### google-analytics.md (feature 25)290291**Purpose:** Register the book as a Google Analytics 4 property and wire the Measurement ID into mkdocs.yml292293**Creates:**294- GA4 property + web data stream (via Claude in Chrome)295- `extra.analytics` block in mkdocs.yml with the G-* Measurement ID296- Build-time tag verification, commit, and gh-deploy297298**Prerequisites:**299- Claude in Chrome extension connected; user logged into Google Analytics300- site_url set in mkdocs.yml301302### learning-graph-viewer.md303304**Purpose:** Add interactive learning graph exploration to existing textbook305306**Creates:**307- Interactive vis-network graph viewer308- Search, filtering, and statistics features309- Integration with existing learning-graph.json310311**Prerequisites:**312- Existing MkDocs project313- learning-graph.json file present314315### skill-tracker.md316317**Purpose:** Set up Claude Code skill usage tracking318319**Creates:**320- Hook scripts for tracking skill invocations321- Activity log directory structure322- Reporting scripts for usage analysis323324**Prerequisites:**325- Claude Code installed326- ~/.claude directory exists327328### social-media-preview.md329330**Purpose:** Install a Cairo-free MkDocs hook that emits Open Graph and Twitter Card meta tags on every page331332**Creates:**333- `plugins/social_override.py` — `on_post_page` hook that injects/replaces `og:title`, `og:description`, `og:image`, `og:type`, `og:url`, and `twitter:*` tags334- `hooks:` block in `mkdocs.yml` referencing the new file335336**Features:**337- Reads `image:`, `title:`, `description:` from each page's frontmatter; falls back to `img/cover.png` and the site-wide values338- Emits absolute `og:image` URLs by joining `site_url` with the image path (so crawlers and `bk-check-social-cover` can HEAD-request them)339- Works without `mkdocs-material[imaging]` / Cairo — the common-case default340- Compatible with the full `social` plugin when Cairo is present: replaces its auto-generated `/assets/images/social/...` URLs with the declared `cover.png`341- Verified via `~/.local/bin/bk-check-social-cover` (which enforces `og:image` basename = `cover.png` and image reachability)342343**Prerequisites:**344- Existing MkDocs Material project with `site_url:` set345- `docs/img/cover.png` (use `cover-image-generator.md` or `home-page-template.md` first if missing)346- Home page frontmatter with `title:` and `description:` (typically from `home-page-template.md`)347348### home-page-template.md349350**Purpose:** Create professional home page with cover image and social media optimization351352**Creates:**353- docs/index.md with proper frontmatter metadata354- AI image generation prompts for cover with montage background355- Open Graph and Twitter Card configuration356357**Features:**358- Cover image design guidance (1.91:1 aspect ratio)359- Montage element suggestions by topic360- Social media preview optimization361- Example prompts for various book themes362363**Prerequisites:**364- Existing MkDocs project365- Access to AI image generator (DALL-E, Midjourney, etc.)366367### learning-mascot.md368369**Purpose:** Design and implement a pedagogical agent (learning mascot) that guides students through the textbook370371**Creates:**372- Character design (name, species, appearance, personality, catchphrase)373- AI image generation prompts for consistent mascot poses374- Implementation via inline images, custom CSS admonitions, or JavaScript auto-detection375- A mascot test page with automated transparency/4 px trim checks and all seven admonition previews376- CONTENT-GENERATION-GUIDE.md character guidelines for consistent AI-generated content, with the placement rules rendered from `references/mascot-placement-rules.md`377378**Features:**379- Subject-specific mascot suggestions with reasoning380- Seven standard pose variants (neutral, welcome, thinking, tip, warning, encouraging, celebration)381- Three implementation methods at different complexity levels382- Restraint guidelines to prevent overuse383384**Prerequisites:**385- Existing MkDocs Material project386- Access to AI image generator (DALL-E, Midjourney, etc.)387388### instructors-guide.md389390**Purpose:** Generate a comprehensive instructor's/teacher's guide for the textbook391392**Creates:**393- `docs/teachers-guide/index.md` (or `docs/instructors-guide/index.md` for college-level)394- Navigation entry in mkdocs.yml395396**Features:**397- Five levels of intelligent textbooks explained398- Detailed usage instructions for chapters, MicroSims, glossary, FAQ, quizzes, and references399- Classroom tips (before/during/after class suggestions, pacing)400- MicroSim iframe embedding guide for external LMS pages401- Creative Commons license explained in plain English (what you can/cannot do)402- Step-by-step customization guide (fork, clone, change colors/title/logo, deploy)403- Google Analytics setup instructions404- xAPI/LRS overview with FERPA/COPPA/GDPR regulatory warnings405- Learning graph usage tips for teachers406- Pedagogical agent (mascot) documentation (if mascot exists)407- All technical terms defined before use — no assumed prior knowledge408409**Prerequisites:**410- Existing MkDocs Material project411- At least some chapter content written412413### custom-404-page.md414415**Purpose:** Add a custom 404 error page featuring the project's learning mascot416417**Creates:**418- `overrides/404.html` — Jinja2 template extending Material base theme with mascot image, friendly message, and home link419- mkdocs.yml updates for `custom_dir` and `static_templates`420421**Features:**422- Uses the mascot's warning pose (or other pose) centered on the page423- Inherits full site navigation (header, sidebar, footer) from the Material theme424- Customizable message matched to the mascot's personality and voice425- Absolute image paths so the 404 works from any URL depth426427**Prerequisites:**428- Existing MkDocs Material project429- Learning mascot images in `docs/img/mascot/` (use `learning-mascot.md` first if needed)430431### document-status.md432433**Purpose:** Add per-page colored status dots to the navigation sidebar for tracking page lifecycle state434435**Creates:**436- `extra.status` configuration in mkdocs.yml437- CSS rules for colored status dots in extra.css438- `status:` frontmatter on individual pages439440**Features:**441- Three-state workflow (spec-complete → prototype → ready-for-testing)442- Colored dots (red, orange, green) visible in the nav sidebar443- Tooltip text on hover444- Customizable status codes for any workflow445446**Prerequisites:**447- Existing MkDocs Material project448- Custom CSS file referenced in `extra_css`449450### reading-level-analysis.md451452**Purpose:** Analyze Flesch-Kincaid grade level consistency across all chapters453454**Creates:**455- `docs/learning-graph/chapter-reading-levels.md` — per-chapter reading level report456457**Uses script:** `scripts/analyze-reading-levels.py`458459**Features:**460- Strips markdown/HTML formatting to analyze pure prose461- Per-chapter table with FK grade and explanatory notes462- Summary statistics (mean, median, range, standard deviation)463- Interpretation section explaining whether variation is meaningful464- Identifies vocabulary-driven score inflation vs. genuine difficulty differences465466**Prerequisites:**467- Existing MkDocs project with chapters in `docs/chapters/`468- Python `textstat` library (`pip install textstat`)469470### book-metrics.md471472**Purpose:** Generate comprehensive book-wide and per-chapter metrics for an intelligent textbook473474**Creates:**475- `docs/learning-graph/book-metrics.md` — Book Composition + Student-Facing Content Metrics tables476- `docs/learning-graph/chapter-metrics.md` — per-chapter breakdown477- merges a `metrics` block of book-wide totals into `docs/learning-graph/book-metadata.json` (author fields preserved)478479**Uses script:** `bk-generate-book-metrics` (resolves `$BK_HOME/src/book-metrics/book-metrics.py`); fallback `python3 "$BK_HOME/src/book-metrics/book-metrics.py" docs`480481**Features:**482- Tracks all 12 book-composition elements with Required/Recommended/Optional status483- Counts concepts, chapters, MicroSims, stories, glossary terms, FAQs, quiz questions, references, diagrams, equations, words, links, appendices, mascot poses484- Estimates equivalent printed pages and records the development stage485- Produces the totals the intelligent-textbooks case-studies index displays486487**Prerequisites:**488- Existing MkDocs project with chapters in `docs/chapters/`489- `$BK_HOME` exported and `bk-generate-book-metrics` on `$PATH`490491### favicon-generator.md492493**Purpose:** Generate a web-compliant multi-resolution `favicon.ico` from the mascot's `neutral.png`494495**Creates:**496- `docs/img/favicon.ico` — multi-resolution icon (16, 32, 48, 64, 128, 256 px) embedded in a single `.ico` file497498**Uses script:** `scripts/generate-favicon.py`499500**How it works:**501- Detects the bounding box of non-transparent pixels (trims invisible padding)502- Centers the visible content on a square canvas with configurable padding503- Downscales to each favicon size using Lanczos resampling504- Supports transparent or white background canvas505506**Prerequisites:**507- Mascot image at `docs/img/mascot/neutral.png` (image need not be square)508- Python `Pillow` library (`pip install Pillow`)509510### cover-image-generator.md511512**Purpose:** Craft a high-quality cover image prompt at `docs/img/cover-image-prompt.md`, built from the book's title, course description, concept list, mascot, and MicroSim screenshots. Image auto-generation is optional and only runs if the user explicitly asks for it.513514**Provides:**515- Guidance for selecting 6-10 montage concepts from the book's own content516- A detailed prompt template covering subject/tone, title typography, montage, mascot, style/color, and things to avoid517- Recommended manual review loop: paste the prompt into a text-to-image tool, compare drafts, iterate on the prompt before finalizing518- Optional automated paths (API, browser automation, or local-prompt) with troubleshooting — only used on explicit request519520**Prerequisites:**521- Existing MkDocs project with mkdocs.yml522- docs/course-description.md with book content description523- Only if auto-generation is requested: OpenAI API billing, ChatGPT Pro subscription, or a free AI image generator524525### kanban-board.md526527**Purpose:** Create a GitHub Projects (v2) Kanban board for tracking textbook development progress528529**Creates:**530- GitHub Projects board with Board (Kanban) layout531- Priority field (High / Medium / Low)532- 13 standard textbook milestone draft items533- `docs/project-management.md` with column documentation and workflow guide534- README section about the Kanban board535536**Features:**537- Automated setup via `gh project` CLI commands538- Links project to the repository automatically539- Pre-populated milestones matching the 12-step textbook workflow540- Fallback instructions for manual setup if `gh` commands fail541542**Prerequisites:**543- `gh` CLI installed and authenticated544- `project` scope on the GitHub token (`gh auth refresh -s project`)545- Existing MkDocs project with mkdocs.yml546547### supplementary-content-generator.md548549**Purpose:** Generate all standard supplementary content for an intelligent textbook in a single coordinated workflow550551**Produces (in execution order):**552- `docs/about.md` — professional about page (via `about-page.md` reference)553- `docs/glossary.md` — ISO 11179-compliant glossary (via `glossary-generator` skill)554- `docs/faq.md` — ≥ 30-question FAQ (via `faq-generator` skill)555- `docs/chapters/*/quiz.md` — per-chapter quizzes (via `quiz-generator` skill)556- `docs/chapters/*/references.md` — per-chapter reference lists (via `reference-generator` skill)557- `docs/img/cover.png` — book cover image + social-preview hook (via `cover-image-generator.md` + `social-media-preview.md`)558- Book metrics report (via `bk-generate-book-metrics` script)559- Diagram reports (via `bk-diagram-reports` script)560- `README.md` — GitHub-facing README after metrics, so it can embed content counts (via the `book-publisher` readme route — skill)561- `docs/index.md` — main landing page last, so it can link to all of the above (via `home-page-template.md`)562- Updated `mkdocs.yml` nav entries for all generated files563564**Execution order:** about → glossary → FAQ → quizzes → references → cover image → metrics → diagram reports → README → landing page → nav update → verification565566**Model guidance:** All text-generation steps use Sonnet. Any MicroSim created during this workflow must use `claude-opus-4-7` with `high` thinking — Opus is significantly better at the coding and spatial reasoning MicroSims require.567568**Prerequisites:**569- Existing MkDocs project with `mkdocs.yml`570- `docs/course-description.md` present571- `docs/learning-graph/learning-graph.json` present572- At least one chapter under `docs/chapters/`573574### slide-generator.md575576**Purpose:** Install the slide-viewer MicroSim into an intelligent textbook project and generate presentation-style `slides.md` decks for specified chapters577578**Creates:**579- `docs/sims/slide-viewer/` — viewer shell (main.html, script.js, local.css, index.md) that fetches any rendered MkDocs page URL, splits its content on `<hr>` elements, and renders one slide at a time with keyboard + button navigation580- `docs/chapters/<slug>/slides.md` — per chapter: title slide, content slides separated by `---`, retrieval check, bridge, celebration close581- Three-button nav bar (`Content`, `Slides`, `Slides in Viewer`) at the top of each chapter's `index.md` and its `slides.md`582- mkdocs.yml nav restructured so each chapter with slides has `Content` / `Slides` sub-entries583584**Features:**585- Viewer reads MkDocs' rendered HTML (never raw `.md` — MkDocs doesn't serve `.md` directly)586- Mascot integration: neutral pose on every slide, celebration pose on the last slide (uses `docs/img/mascot/neutral.png` and `celebration.png` if present; silently absent otherwise)587- First/last-slide jump buttons, `Home`/`End` keys, fullscreen, table-of-contents overlay588- Distills chapter `index.md` into 15–28 slides following project voice/style rules589590**Prerequisites:**591- Existing MkDocs Material project with `docs/chapters/` populated592- Chapter `index.md` files with real content (not just scaffold) — guide checks line counts before generating593- Optional: mascot installed via `learning-mascot.md`594595### mascot-placement-rules.md596597**Purpose:** The single source of truth for when a learning mascot may appear, how often, and which pose carries which pedagogical job598599**Used by:** `learning-mascot.md`, `mascot-chapter-updater.md`, `instructors-guide.md`, and the `chapter-content-generator` skill — all of which reference this file rather than restating its rules600601**Contains:**602- The admonition format and the Markdown-vs-raw-HTML image path rules603- The placement table (context → pose → per-chapter count)604- Hard limits: fewer than 10 admonitions per chapter, no back-to-back placement, one welcome and one celebration, 1-3 sentence bodies605- Per-pose instructional-design rules for all seven poses606- The one-time Chapter 1 self-introduction pattern607- The post-generation validation rule608609**Important:** never copy this file's tables or counts into another skill or into a book by hand. Skills reference it by path; books receive a rendered copy via `scripts/render-mascot-guide.py`, spliced between sentinel comments so it can be regenerated. Run `scripts/bk-check-mascot-rules` from the repo root to verify no restatement has crept back in.610611### mascot-chapter-updater.md612613**Purpose:** Retrofit an existing chapter markdown file with mascot admonitions in the right places, following the canonical `references/mascot-placement-rules.md`614615**Creates:**616- In-place edits to the specified chapter file only (no new files)617- A placement plan shown to the user for confirmation before editing618619**Features:**620- LLM-driven workflow for semantic placement (no regex auto-insertion)621- Enforces the hard limits defined in `references/mascot-placement-rules.md` (total ceiling, one welcome and one celebration maximum, no back-to-back placements)622- Image-path guidance for directory-URL rendering (counts `../` from rendered page)623- Voice and body-text rules: 1-3 sentences, in-character, specific to chapter content624- Validation via `scripts/validate-chapter-mascots.py` that flags count limits, back-to-backs, missing mascot images, and body-text length625626**Prerequisites:**627- Mascot images present in `docs/img/mascot/` or `docs/img/mascots/`628- `docs/css/mascot.css` loaded and the mascot-test page renders correctly629- Specific chapter file identified by absolute path630631## Examples632633### Example 1: Ask for Help634**User:** "book-installer help"635**Routing:** Keyword "help" → Display numbered list636**Action:** Show the numbered feature list (Step 1), then wait for user to select a feature637638### Example 2: Add a Specific Feature639**User:** "Add math equation support to my book"640**Routing:** Keyword "math" → `references/mkdocs-features.md`641**Action:** Load mkdocs-features.md, find the Math Equations section, and apply the configuration642643### Example 2b: Select by Number644**User:** "5"645**Routing:** Number selection after help list → `references/mkdocs-features.md`646**Action:** Load mkdocs-features.md, find Math Equations (item 5), and apply the configuration647648### Example 2c: Simple Template649**User:** "1"650**Routing:** Number 1 → `references/init-textbook.md` (canonical scaffold)651**Action:** Load init-textbook.md and scaffold the starter config and docs/ tree652653### Example 3: New Textbook Project654**User:** "I want to create a new intelligent textbook about machine learning" (empty directory)655**Routing:** Keywords "create", "new", "textbook" → `references/init-textbook.md`656**Action:** Read init-textbook.md, gather SITE_NAME/SITE_DESCRIPTION, confirm the substitution table, scaffold from `assets/init-textbook/`657658### Example 3b: Register Google Analytics659**User:** "Add Google Analytics to this book" or "25"660**Routing:** Keywords "google analytics", "GA4", "25" → `references/google-analytics.md`661**Action:** Read google-analytics.md; create the GA4 property, write the G-* ID into mkdocs.yml extra.analytics, verify the tag, deploy662663### Example 4: Add Graph Viewer664**User:** "Add an interactive viewer for the learning graph"665**Routing:** Keywords "viewer", "learning graph", "interactive" → `references/learning-graph-viewer.md`666**Action:** Read learning-graph-viewer.md and follow its workflow667668### Example 5: Track Skill Usage669**User:** "I want to track which skills I use most often"670**Routing:** Keywords "track", "skills", "usage" → `references/skill-tracker.md`671**Action:** Read skill-tracker.md and follow its workflow672673### Example 6: Create Cover Image674**User:** "Help me create a cover image for my textbook"675**Routing:** Keywords "cover image", "textbook" → `references/home-page-template.md`676**Action:** Read home-page-template.md and follow its workflow677678### Example 7: Set Up Home Page with Social Sharing679**User:** "I need to add og:image metadata to my home page"680**Routing:** Keywords "og:image", "home page" → `references/home-page-template.md`681**Action:** Read home-page-template.md and follow its workflow682683### Example 8: Generate Cover Image Prompt684**User:** "generate cover image" or "book-installer generate cover image"685**Routing:** Keywords "generate cover image" → `references/cover-image-generator.md`686**Action:** Read cover-image-generator.md, gather source material (title, course description, concept list, mascot, MicroSim screenshots), write `docs/img/cover-image-prompt.md`, and recommend the user paste it into a text-to-image tool and review drafts. Only ask about API key/ChatGPT Pro/macOS and run `generate-cover.sh` if the user explicitly requests auto-generation.687688### Example 9: Add a Learning Mascot689**User:** "I want to add a mascot character to my math textbook"690**Routing:** Keywords "mascot", "character" → `references/learning-mascot.md`691**Action:** Read learning-mascot.md, guide user through character design, generate AI image prompts, and implement chosen method (inline, CSS admonitions, or JS detection)692693### Example 10: Generate Feature Checklist694**User:** "generate a feature checklist" or "what features do I have"695**Routing:** Keywords "feature checklist" → `references/feature-checklist-generator.md`696**Action:** Read feature-checklist-generator.md, run the detection script, generate docs/feature-checklist.md with detected statuses697698### Example 11: Generate Instructor's Guide699**User:** "add a teacher's guide" or "create instructor guide"700**Routing:** Keywords "teacher guide", "instructor guide" → `references/instructors-guide.md`701**Action:** Read instructors-guide.md, gather project variables from mkdocs.yml/course-description.md/CLAUDE.md, generate the guide with all variables substituted, add to navigation702703### Example 12: Create Kanban Board704**User:** "set up a kanban board for my textbook" or "create a project board"705**Routing:** Keywords "kanban", "project board" → `references/kanban-board.md`706**Action:** Read kanban-board.md, verify gh auth with project scope, create the GitHub Project, link to repo, populate milestones, create docs/project-management.md, update nav and README707708### Example 13: Generate About Page709**User:** "create an about page" or "add about.md with author bio and citations"710**Routing:** Keywords "about page", "about", "author bio", "citation" → `references/about-page.md`711**Action:** Read about-page.md, gather project variables from mkdocs.yml/course-description.md, generate docs/about.md with all sections (motivation, author bio, citation formats), add to navigation712713### Example 14: Add Mascots to an Existing Chapter714**User:** "add Sparky admonitions to chapter 2" or "place the mascot in docs/chapters/02-ohms-law/index.md"715**Routing:** Keywords "mascot chapter", "place mascot", "add mascot to chapter" → `references/mascot-chapter-updater.md`716**Action:** Read mascot-chapter-updater.md, survey the chapter, propose a placement plan with line numbers, wait for user confirmation, apply edits, run validate-chapter-mascots.py, and address any flags717718### Example 15: Generate Favicon from Mascot719**User:** "generate favicon from mascot" or "create favicon.ico from neutral.png"720**Routing:** Keywords "generate favicon", "mascot favicon", "favicon from mascot" → `references/favicon-generator.md`721**Action:** Read favicon-generator.md, verify `docs/img/mascot/neutral.png` exists and Pillow is installed, run `scripts/generate-favicon.py` from the project root, then update `theme.favicon` in mkdocs.yml to `img/favicon.ico`722723### Example 15b: Install Social Media Preview Hook724**User:** "add the social media preview mkdocs hook" or "my bk-check-social-cover is failing" or "install og:image meta tags"725**Routing:** Keywords "social media preview", "og:image", "bk-check-social-cover", "social hook" → `references/social-media-preview.md`726**Action:** Read social-media-preview.md, create `plugins/social_override.py` at the project root with the exact code in the reference, add a top-level `hooks: - plugins/social_override.py` block to `mkdocs.yml`, run `mkdocs build`, verify the nine og:* / twitter:* meta tags appear in `site/index.html`, then run `bk-check-social-cover` against either the deployed URL or a local server staging the build under `/<project>/`727728### Example 17: Generate All Supplementary Content729**User:** "generate all supplementary content" or "complete the book" or "39"730**Routing:** Keywords "supplementary content", "complete the book", "39" → `references/supplementary-content-generator.md`731**Action:** Read supplementary-content-generator.md. First inventory existing files. Then execute Steps 2–12 in order: generate about page, landing pag732733…(truncated)