{"id":42041241,"url":"https://github.com/dmccreary/intelligent-textbooks","last_synced_at":"2026-01-26T05:34:55.419Z","repository":{"id":266307510,"uuid":"897978796","full_name":"dmccreary/intelligent-textbooks","owner":"dmccreary","description":"How to use AU and mkdocs material with education theory to create intelligent textbooks","archived":false,"fork":false,"pushed_at":"2026-01-17T18:23:44.000Z","size":239894,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-18T04:41:50.756Z","etag":null,"topics":["ai","books","graph","mkdocs-material"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmccreary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-03T15:18:15.000Z","updated_at":"2026-01-17T18:23:26.000Z","dependencies_parsed_at":"2024-12-03T16:36:33.860Z","dependency_job_id":"47905919-d2c3-4de2-93e0-d04d4ce9528d","html_url":"https://github.com/dmccreary/intelligent-textbooks","commit_stats":null,"previous_names":["dmccreary/mkdocs-for-intelligent-textbooks","dmccreary/intelligent-textbooks"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dmccreary/intelligent-textbooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmccreary%2Fintelligent-textbooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmccreary%2Fintelligent-textbooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmccreary%2Fintelligent-textbooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmccreary%2Fintelligent-textbooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmccreary","download_url":"https://codeload.github.com/dmccreary/intelligent-textbooks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmccreary%2Fintelligent-textbooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28767320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T03:54:34.369Z","status":"ssl_error","status_checked_at":"2026-01-26T03:54:33.031Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","books","graph","mkdocs-material"],"created_at":"2026-01-26T05:34:54.877Z","updated_at":"2026-01-26T05:34:55.403Z","avatar_url":"https://github.com/dmccreary.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Building Intelligent Textbooks With AI\n\n[![Built with Material for MkDocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?style=for-the-badge\u0026logo=MaterialForMkDocs\u0026logoColor=white)](https://squidfunk.github.io/mkdocs-material/)\n[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-222222?style=for-the-badge\u0026logo=GitHub%20Pages\u0026logoColor=white)](https://dmccreary.github.io/intelligent-textbooks/)\n[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/)\n[![p5.js](https://img.shields.io/badge/p5.js-ED225D?style=for-the-badge\u0026logo=p5.js\u0026logoColor=white)](https://p5js.org/)\n[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg?style=for-the-badge)](https://creativecommons.org/licenses/by-nc-sa/4.0/)\n\n\u003e 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.\n\n## 🌐 Website\n\n**[View the Live Site →](https://dmccreary.github.io/intelligent-textbooks/)**\n\n## 📖 About\n\nThis 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](https://dmccreary.github.io/intelligent-textbooks/glossary/#learning-graph) as their core data structure to ground content generation and guide learning agents.\n\n### Why Intelligent Textbooks?\n\nTraditional 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:\n\n- **Adapt to individual learning paths** using concept dependency graphs\n- **Provide interactive simulations** (MicroSims) for hands-on learning  \n- **Generate content dynamically** using AI prompts and workflows\n- **Scale globally** using free, open-source tools\n\n## 🏗️ Architecture\n\n### Core Technologies\n\n- **[MkDocs](https://www.mkdocs.org/)** - Static site generator optimized for documentation\n- **[Material Theme](https://squidfunk.github.io/mkdocs-material/)** - Modern, responsive theme with advanced features\n- **[p5.js](https://p5js.org/)** - Interactive simulations and visualizations\n- **[Python](https://www.python.org/)** - Content processing and analytics scripts\n- **[GitHub Pages](https://pages.github.com/)** - Free hosting for public educational content\n\n### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| **MicroSims** | Interactive p5.js simulations embedded via iframes |\n| **Learning Graphs** | Concept dependency visualizations and data |\n| **AI Prompts** | Structured prompts for content generation workflows |\n| **Custom Plugins** | Social media card overrides and extensions |\n| **Analytics Tools** | Python scripts for site metrics and content analysis |\n\n## 📁 Project Structure\n\n```\nintelligent-textbooks/\n├── docs/                     # All markdown content\n│   ├── concepts/            # Educational theory and best practices\n│   ├── tutorial/            # Getting started guides\n│   ├── prompts/             # AI content generation prompts\n│   ├── workflow/            # Step-by-step content creation processes\n│   ├── sims/                # Interactive p5.js microsimulations\n│   │   ├── learning-graph/  # Concept dependency visualizations\n│   │   ├── blooms-taxonomy/ # Educational taxonomy simulations\n│   │   └── templates/       # Reusable MicroSim templates\n│   └── css/extra.css        # Custom styling\n├── src/                     # Python utility scripts\n│   ├── site-analytics/      # Website metrics and reporting\n│   ├── csv-to-json/         # Data format conversion tools\n│   └── mk-book-toc/         # Table of contents generation\n├── plugins/                 # Custom MkDocs plugins\n│   └── social_override.py   # Social media card customization\n├── mkdocs.yml              # Site configuration\n└── CLAUDE.md               # AI development guidance\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.7+\n- [Conda](https://docs.conda.io/en/latest/) (recommended) or pip\n- [Git](https://git-scm.com/)\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/dmccreary/intelligent-textbooks.git\n   cd intelligent-textbooks\n   ```\n\n2. **Set up Python environment**\n   ```bash\n   # Using conda (recommended)\n   conda create -n mkdocs python=3\n   conda activate mkdocs\n   \n   # Install dependencies\n   pip install mkdocs \"mkdocs-material[imaging]\"\n   ```\n\n3. **For social card generation (macOS)**\n   ```bash\n   brew install cairo freetype libffi libjpeg libpng zlib\n   export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib\n   ```\n\n### Development\n\n```bash\n# Build the site\nmkdocs build\n\n# Run local development server\nmkdocs serve\n# Visit http://localhost:8000\n\n# Deploy to GitHub Pages\nmkdocs gh-deploy\n```\n\n## 📚 Content Areas\n\n### 🎓 Educational Concepts\n- **Five Levels of Intelligent Textbooks** - Progressive enhancement framework\n- **Bloom's Taxonomy** - Cognitive learning objectives\n- **Learning Graphs** - Concept dependency mapping\n- **Scaffolding** - Structured learning support\n\n### 🤖 AI Workflows  \n- **Content Generation Prompts** - Structured AI interactions\n- **Learning Graph Creation** - Automated concept mapping\n- **Quality Assessment** - Content evaluation metrics\n- **Semantic Search** - Intelligent content discovery\n\n### 🎮 Interactive Elements\n- **MicroSims** - p5.js educational simulations\n- **Concept Visualizations** - Interactive diagrams\n- **Learning Graph Viewer** - Dynamic concept exploration\n- **Template Library** - Reusable simulation components\n\n## 🛠️ Creating MicroSims\n\nMicroSims are self-contained interactive educational simulations. Each follows this structure:\n\n```\ndocs/sims/your-sim-name/\n├── index.md          # Documentation and embedding\n├── main.html         # Standalone HTML page  \n└── your-sim-name.js  # p5.js simulation code\n```\n\n**Template Usage:** Start with `docs/sims/templates/` for consistent structure and styling.\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Contribution Guidelines\n\n- Follow existing MicroSim structure for interactive content\n- Update navigation in `mkdocs.yml` for new pages\n- Test locally with `mkdocs serve` before submitting\n- Include appropriate metadata for social sharing\n\n## 📊 Analytics \u0026 Metrics\n\nThe `src/site-analytics/` directory contains Python tools for:\n\n- **Site Performance Metrics** - Page views, engagement analysis\n- **Content Quality Assessment** - Educational effectiveness measures  \n- **Learning Graph Analysis** - Concept coverage and dependencies\n- **Report Generation** - Automated insights and recommendations\n\n## 🎯 Educational Philosophy\n\nThis 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:\n\n- Generates content in real-time based on learner needs\n- Uses interactive storytelling and simulations  \n- Implements learning graphs for optimal concept sequencing\n- Provides scaffolded support that adapts to individual progress\n\n## 📄 License\n\nThis project is licensed under the [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-nc-sa/4.0/) - see the [LICENSE](docs/license.md) file for details.\n\n**You are free to:**\n- **Share** — copy and redistribute the material in any medium or format\n- **Adapt** — remix, transform, and build upon the material\n\n**Under the following terms:**\n- **Attribution** — You must give appropriate credit and indicate if changes were made\n- **NonCommercial** — You may not use the material for commercial purposes  \n- **ShareAlike** — If you remix or build upon the material, you must distribute your contributions under the same license\n\n## 🔗 Links \u0026 Resources\n\n- **📖 [Documentation](https://dmccreary.github.io/intelligent-textbooks/)**\n- **🐛 [Issues](https://github.com/dmccreary/intelligent-textbooks/issues)**\n- **💬 [Discussions](https://github.com/dmccreary/intelligent-textbooks/discussions)**\n- **📧 [Contact](https://dmccreary.github.io/intelligent-textbooks/contact/)**\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ for educators worldwide**\n\n*Empowering teachers to create intelligent, adaptive learning experiences*\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmccreary%2Fintelligent-textbooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmccreary%2Fintelligent-textbooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmccreary%2Fintelligent-textbooks/lists"}