dmccreary/claude-skills/book-installer

Book Installer

Version: 1.0.4

Changelog

• v1.0.4 — references/home-page-template.md now has a required

Landing Page Title Rule: when the cover image renders the book title, the landing page hides the duplicate h1 with the <style> block and starts the cover image's alt text with the exact book title, because display: none removes the h1 from the accessibility tree and the alt text is then what a screen reader announces. The rule also forbids hiding the h1 over a placeholder cover that does not show the title. The Step 8 template, Step 10 snippet, complete example, and troubleshooting section follow the rule (the old template hid a generic # Welcome heading and gave the cover only the bare title as alt text). The scaffold docs/index.md, the supplementary-content generator (Step 11), and the cover-image generator point to the rule. Existing books should add the same <style> block and title-first alt text to their docs/index.md (found in oer-evaluator).

• v1.0.3 — The init-textbook mkdocs.yml template's exclude_docs now

lists **/cover-image-prompt.md. The cover-image-generator guide writes docs/img/cover-image-prompt.md, but the template only excluded cover-prompt.md, so every new book published its cover prompt as a stray page (found in oer-evaluator). Books scaffolded earlier should add the same line to their own mkdocs.yml. This release also updates the book-metrics feature description in this file to mention the Reading Level column and the \( \) / \[ \] equation detection.

• v1.0.2 — The canonical mascot CSS in references/learning-mascot.md

(Step 5) now fixes the admonition image's height at --mascot-size and sets width: auto, dropping the square box and object-fit: contain. Mascot poses are portrait, so the square box shrank them and left visible empty space on both sides of the bird (a 185×280 pose drew 59px wide inside a 90px box in oer-evaluator). Existing books should make the same change in their own docs/css/mascot.css.

• v1.0.1 — The canonical mascot CSS in references/learning-mascot.md

(Step 5) now targets .md-typeset img.mascot-admonition-img instead of the bare .mascot-admonition-img. Material's .md-typeset img { height: auto } outranked the bare class selector, so only the width applied and portrait poses rendered far taller than --mascot-size (90px-wide poses measured 93–210px tall in clocks-and-watches). The class name itself is unchanged, so chapter markdown, validate-chapter-mascots.py, and glightbox skip_classes need no edits. Existing books should update the selector in their own docs/css/mascot.css.

• 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 old fixed per-chapter ceiling is replaced with an informal guideline scaled to the chapter's concept count (~1 admonition per 2 concepts, adjusted for reader age), advisory only and never a hard failure. scripts/validate-chapter-mascots.py now also 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)
41. MkDocs-serve warning - MkDocs-only hook that warns when a Zensical-built book is previewed with `mkdocs serve` (recommended for every Zensical-designed book during the MkDocs-to-Zensical transition)
 
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