A comprehensive guide to designing and building online interactive intelligent textbooks using open source tools, with a focus on interactive learning experiences and AI-powered content generation.
This project is a series of resources to help teachers worldwide create the foundation for free and open intelligent textbooks. Our focus is on helping instructors create Level 2 textbooks that use a learning graph as their core data structure to ground content generation and guide learning agents.
Traditional textbooks are static. Intelligent textbooks adapt to learners, provide interactive experiences, and leverage AI to create personalized educational content. This project demonstrates how to build textbooks that:
- Adapt to individual learning paths using concept dependency graphs
- Provide interactive simulations (MicroSims) for hands-on learning
- Generate content dynamically using AI prompts and workflows
- Scale globally using free, open-source tools
- MkDocs - Static site generator optimized for documentation
- Material Theme - Modern, responsive theme with advanced features
- p5.js - Interactive simulations and visualizations
- Python - Content processing and analytics scripts
- GitHub Pages - Free hosting for public educational content
| Component | Description |
|---|---|
| MicroSims | Interactive p5.js simulations embedded via iframes |
| Learning Graphs | Concept dependency visualizations and data |
| AI Prompts | Structured prompts for content generation workflows |
| Custom Plugins | Social media card overrides and extensions |
| Analytics Tools | Python scripts for site metrics and content analysis |
intelligent-textbooks/
├── docs/ # All markdown content
│ ├── concepts/ # Educational theory and best practices
│ ├── tutorial/ # Getting started guides
│ ├── prompts/ # AI content generation prompts
│ ├── workflow/ # Step-by-step content creation processes
│ ├── sims/ # Interactive p5.js microsimulations
│ │ ├── learning-graph/ # Concept dependency visualizations
│ │ ├── blooms-taxonomy/ # Educational taxonomy simulations
│ │ └── templates/ # Reusable MicroSim templates
│ └── css/extra.css # Custom styling
├── src/ # Python utility scripts
│ ├── site-analytics/ # Website metrics and reporting
│ ├── csv-to-json/ # Data format conversion tools
│ └── mk-book-toc/ # Table of contents generation
├── plugins/ # Custom MkDocs plugins
│ └── social_override.py # Social media card customization
├── mkdocs.yml # Site configuration
└── CLAUDE.md # AI development guidance
-
Clone the repository
git clone https://github.com/dmccreary/intelligent-textbooks.git cd intelligent-textbooks -
Set up Python environment
# Using conda (recommended) conda create -n mkdocs python=3 conda activate mkdocs # Install dependencies pip install mkdocs "mkdocs-material[imaging]"
-
For social card generation (macOS)
brew install cairo freetype libffi libjpeg libpng zlib export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib
# Build the site
mkdocs build
# Run local development server
mkdocs serve
# Visit http://localhost:8000
# Deploy to GitHub Pages
mkdocs gh-deploy- Five Levels of Intelligent Textbooks - Progressive enhancement framework
- Bloom's Taxonomy - Cognitive learning objectives
- Learning Graphs - Concept dependency mapping
- Scaffolding - Structured learning support
- Content Generation Prompts - Structured AI interactions
- Learning Graph Creation - Automated concept mapping
- Quality Assessment - Content evaluation metrics
- Semantic Search - Intelligent content discovery
- MicroSims - p5.js educational simulations
- Concept Visualizations - Interactive diagrams
- Learning Graph Viewer - Dynamic concept exploration
- Template Library - Reusable simulation components
MicroSims are self-contained interactive educational simulations. Each follows this structure:
docs/sims/your-sim-name/
├── index.md # Documentation and embedding
├── main.html # Standalone HTML page
└── your-sim-name.js # p5.js simulation code
Template Usage: Start with docs/sims/templates/ for consistent structure and styling.
We welcome contributions! Here's how to get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow existing MicroSim structure for interactive content
- Update navigation in
mkdocs.ymlfor new pages - Test locally with
mkdocs servebefore submitting - Include appropriate metadata for social sharing
The src/site-analytics/ directory contains Python tools for:
- Site Performance Metrics - Page views, engagement analysis
- Content Quality Assessment - Educational effectiveness measures
- Learning Graph Analysis - Concept coverage and dependencies
- Report Generation - Automated insights and recommendations
This project implements concepts from Neal Stephenson's "The Diamond Age," specifically the Young Lady's Illustrated Primer - a vision of adaptive, personalized educational technology that:
- Generates content in real-time based on learner needs
- Uses interactive storytelling and simulations
- Implements learning graphs for optimal concept sequencing
- Provides scaffolded support that adapts to individual progress
This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License - see the LICENSE file for details.
You are free to:
- Share — copy and redistribute the material in any medium or format
- Adapt — remix, transform, and build upon the material
Under the following terms:
- Attribution — You must give appropriate credit and indicate if changes were made
- NonCommercial — You may not use the material for commercial purposes
- ShareAlike — If you remix or build upon the material, you must distribute your contributions under the same license
- 📖 Documentation
- 🐛 Issues
- 💬 Discussions
- 📧 Contact
Built with ❤️ for educators worldwide
Empowering teachers to create intelligent, adaptive learning experiences