Book Installer

Book Installer

Overview

This meta-skill handles installation and setup tasks for intelligent textbook projects. It consolidates three 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
• Installing a learning graph viewer
• Setting up skill usage tracking with hooks
• 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):

 1. Simple mkdocs.yml template - Minimal starter config for new projects
 2. Site logo - Add custom logo to header
 3. Favicon - Browser tab/bookmark icon
 4. Cover image & social preview - Home page image + og:image metadata
 4b. Generate cover image - Auto-generate cover using AI (API or ChatGPT)
 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

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

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?
  → YES: mkdocs-template.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 cover image automatically using AI?
  → YES: cover-image-generator.md (guides through API vs ChatGPT options)

Creating a cover image MANUALLY or setting up home page with social metadata?
  → YES: home-page-template.md

Want to generate a feature checklist showing what's implemented?
  → YES: feature-checklist-generator.md

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

1. Prerequisites and requirements
2. Step-by-step installation commands
3. Configuration options
4. Verification steps
5. 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

mkdocs-template.md

Purpose: Bootstrap a complete MkDocs Material intelligent textbook project

Creates:

• Conda virtual environment named 'mkdocs'
• Full MkDocs Material project structure
• Custom CSS for branding
• Social media card plugins
• GitHub Pages deployment configuration
• URI scheme in extra section for global discoverability

URI Scheme: New projects automatically include the textbook schema in mkdocs.yml:

extra:
  schema: https://dmccreary.github.io/intelligent-textbooks/ns/textbook/v1

See the URI Scheme documentation for details.

Prerequisites:

• Conda installed
• Git installed
• GitHub repository created

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

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
• CLAUDE.md character guidelines for consistent AI-generated content

Features:

• Subject-specific mascot suggestions with reasoning
• Six standard pose variants (welcome, thinking, tip, warning, celebration, encouraging)
• 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.)

cover-image-generator.md

Purpose: Auto-generate cover images using the generate-cover.sh script

Provides:

• Interactive questionnaire to determine best workflow
• Commands for API, ChatGPT Pro, or manual generation
• Troubleshooting for common issues

Workflows:

• Full Auto: OpenAI API with active billing (fastest)
• Browser Auto: ChatGPT Pro + macOS (opens browser, pastes prompt)
• Local Prompt: ChatGPT Pro, any OS (displays prompt for manual copy)
• Fallback: Free tier options with manual generation

Prerequisites:

• Existing MkDocs project with mkdocs.yml
• docs/course-description.md with book content description
• One of: OpenAI API billing, ChatGPT Pro subscription, or free AI image generator

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/mkdocs-template.md (minimal section) Action: Load mkdocs-template.md and create a simple mkdocs.yml starter config

Example 3: New Textbook Project

User: "I want to create a new intelligent textbook about machine learning" Routing: Keywords "create", "new", "textbook" → references/mkdocs-template.md Action: Read mkdocs-template.md and follow its workflow

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 Automatically

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, ask user about their resources (API key, ChatGPT Pro, macOS), then run the appropriate generate-cover.sh command

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

Common Workflows

Full Project Setup

For a complete new project, users typically run these installations in order:

1. mkdocs-template.md - Create the project structure
2. cover-image-generator.md - Auto-generate cover image using AI
3. home-page-template.md - Configure home page with cover image metadata
4. learning-graph-viewer.md - Add graph visualization (after learning graph exists)
5. skill-tracker.md - Enable usage analytics (optional)

Verification Commands

After any installation, verify with:

# For MkDocs projects
mkdocs serve
# Visit http://127.0.0.1:8000/[project-name]/

# For skill tracker
cat ~/.claude/activity-logs/skill-usage.jsonl | tail -5