🚀 zer0-mistakes

The AI-Native Jekyll Theme for GitHub Pages

AI-augmented • Agent-ready • Docker-first • Bootstrap 5.3 • Privacy-compliant • Zero-configuration

Built from the ground up to automate, facilitate, and integrate with modern AI workflows — from one-line self-healing install to multi-agent code guidance (Copilot, Codex, Cursor, Claude Code, Aider) to AI-generated preview images and AIEO content optimization for AI citation.

Quick Start • AI Workflow • Features • Documentation • Contributing

📖 Table of Contents

• Overview
• Quick Start
• AI-Native Workflow
• Architecture
• Key Features
• Installation Methods
• Project Structure
• Development Workflow
• Deployment
• Documentation
• Release System
• Roadmap
• FAQ
• Glossary
• Contributing
• Support
• AIEO-Optimized

Overview

zer0-mistakes is an AI-native Jekyll theme engineered to eliminate setup friction and accelerate every stage of the content lifecycle with AI automation, facilitation, and integration. Docker containerization, multi-agent guidance files, AI-powered tooling, and 43 documented features take you from zero to deployed — and zero to AI-collaborative — in under 5 minutes.

AI is a first-class citizen, not an afterthought:

• 🤖 AI-powered installation — install.sh self-heals across macOS / Linux / Windows (WSL) with ~95% success rate
• 🧠 Multi-agent integration — Drop-in AGENTS.md + .github/copilot-instructions.md + .github/instructions/*.instructions.md + .github/prompts/*.prompt.md + .cursor/commands/ work with Copilot, Codex, Cursor, Claude Code, Aider, Jules, Continue
• 🎨 AI preview-image generation — Jekyll plugin + script generate OpenAI/DALL·E images for posts missing previews (_plugins/preview_image_generator.rb)
• 🤝 AI-facilitated releases — Conventional-commit analyzer auto-determines semantic version bumps and writes the changelog (scripts/analyze-commits.sh)
• 🔍 AIEO-optimized output — Structured data, entity density, FAQ schema, and definitional precision so AI engines cite your site accurately

graph LR
    subgraph "🎯 Your Goal"
        A[Beautiful Website]
    end
    
    subgraph "⚡ zer0-mistakes"
        B[One Command] --> C[Auto-Configure]
        C --> D[Docker Ready]
        D --> E[Live Preview]
    end
    
    subgraph "🚀 Result"
        F[Production Site]
    end
    
    A --> B
    E --> F
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9

Why zer0-mistakes?

🚀 Quick Start

Prerequisites

• Docker Desktop (download)
• Git (download)

One-Line Installation

mkdir my-site && cd my-site && curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash

Start Development

docker-compose up
# 🌐 Open http://localhost:4000

sequenceDiagram
    participant You
    participant InstallScript as Install Script
    participant Docker
    participant Browser

    You->>InstallScript: curl ... | bash
    InstallScript->>InstallScript: Detect platform
    InstallScript->>InstallScript: Download theme files
    InstallScript->>InstallScript: Configure Docker
    InstallScript-->>You: ✅ Ready

    You->>Docker: docker-compose up
    Docker->>Docker: Build Jekyll container
    Docker->>Docker: Install dependencies
    Docker-->>Browser: Serve on :4000

    Browser-->>You: 🎉 Live site

🤖 AI-Native Workflow

zer0-mistakes treats AI as core infrastructure across install → author → build → release → discover. Every layer is wired for automation, facilitation, and integration with the AI tools you already use.

flowchart LR
    subgraph Install["🤖 AI Install"]
        I1[install.sh<br/>self-healing]
    end
    subgraph Author["🧠 AI Authoring"]
        A1[Copilot]
        A2[Codex]
        A3[Cursor]
        A4[Claude Code]
        A5[Aider]
    end
    subgraph Build["🎨 AI Content"]
        B1[OpenAI<br/>Preview Images]
        B2[AI Frontmatter<br/>Maintainer prompt]
    end
    subgraph Release["🚀 AI Release"]
        R1[Commit Analyzer]
        R2[Auto Changelog]
        R3[Semantic Bump]
    end
    subgraph Discover["🔍 AIEO Discovery"]
        D1[JSON-LD Schema]
        D2[FAQ + Glossary]
        D3[Entity Density]
    end

    Install --> Author --> Build --> Release --> Discover

    style Install fill:#e3f2fd
    style Author fill:#f3e5f5
    style Build fill:#fff3e0
    style Release fill:#e8f5e9
    style Discover fill:#fce4ec

What’s wired for AI

Quick AI tasks

# Generate AI preview images for posts missing previews (needs OPENAI_API_KEY)
./scripts/generate-preview-images.sh --collection posts

# Preview before generating (no API calls)
./scripts/generate-preview-images.sh --dry-run --verbose

# Let AI analyze commits and propose the next version bump
./scripts/analyze-commits.sh HEAD~10..HEAD

# Run the AI-facilitated release pipeline (validate → version → changelog → publish)
./scripts/bin/release patch --dry-run

Drop-in for any AI editor

Clone the repo (or fork) and your editor’s AI agent will pick up project context automatically:

• GitHub Copilot / VS Code → reads .github/copilot-instructions.md + .github/instructions/*.instructions.md
• Cursor → reads .cursor/commands/ for slash-commands; falls back to AGENTS.md
• Claude Code / Codex / Aider / Jules / Continue → read AGENTS.md per the agents.md convention
• Custom agents → Load layered guidance from .github/ on demand

No configuration required. The guidance is layered — agents read only what’s needed for the file they’re touching.

🏗 Architecture

System Overview

flowchart TB
    subgraph Input["📝 Content Layer"]
        MD[Markdown Files]
        DATA[YAML Data]
        ASSETS[Static Assets]
    end
    
    subgraph Theme["🎨 Theme Layer"]
        LAYOUTS[_layouts/]
        INCLUDES[_includes/]
        SASS[_sass/]
    end
    
    subgraph Build["⚙️ Build Layer"]
        JEKYLL[Jekyll Engine]
        PLUGINS[Plugins]
        LIQUID[Liquid Templates]
    end
    
    subgraph Output["🌐 Output Layer"]
        HTML[Static HTML]
        CSS[Compiled CSS]
        JS[JavaScript]
    end
    
    subgraph Deploy["🚀 Deploy Layer"]
        GHPAGES[GitHub Pages]
        DOCKER[Docker Container]
        CDN[CDN/Custom Host]
    end
    
    MD --> JEKYLL
    DATA --> JEKYLL
    ASSETS --> JEKYLL
    
    LAYOUTS --> JEKYLL
    INCLUDES --> JEKYLL
    SASS --> JEKYLL
    
    JEKYLL --> HTML
    JEKYLL --> CSS
    JEKYLL --> JS
    
    HTML --> GHPAGES
    HTML --> DOCKER
    HTML --> CDN

Technology Stack

pie title Technology Distribution
    "Jekyll (Static Gen)" : 25
    "Bootstrap 5.3 (UI)" : 20
    "Docker (Dev Env)" : 18
    "AI Tooling & Agents" : 15
    "Liquid (Templates)" : 12
    "PostHog (Analytics)" : 10

✨ Key Features

🤖 AI-Powered Installation

The ~1,100-line install.sh script provides intelligent platform detection and Docker configuration:

flowchart TD
    START([Start Installation]) --> DETECT[Detect Platform]
    DETECT --> CHECK{Prerequisites OK?}
    
    CHECK -->|Yes| DOWNLOAD[Download Theme]
    CHECK -->|No| GUIDE[Show Requirements]
    
    DOWNLOAD --> CONFIG[Configure Docker]
    CONFIG --> VALIDATE{Build Success?}
    
    VALIDATE -->|Yes| DONE([✅ Ready!])
    VALIDATE -->|No| LOGS[Show Error Logs]
    
    style START fill:#e3f2fd
    style DONE fill:#c8e6c9

🐳 Docker-First Development

Zero local dependencies required. Works identically across all platforms:

# docker-compose.yml - That's all you need!
services:
  jekyll:
    image: jekyll/jekyll:latest
    platform: linux/amd64
    command: jekyll serve --config "_config.yml,_config_dev.yml"
    ports: ["4000:4000"]
    volumes: ["./:/app"]

🔒 Privacy-First Analytics

GDPR/CCPA compliant PostHog integration with granular consent:

stateDiagram-v2
    [*] --> PageLoad
    PageLoad --> ConsentCheck
    
    ConsentCheck --> Disabled: DNT Enabled
    ConsentCheck --> ShowBanner: No Consent
    ConsentCheck --> Tracking: Has Consent
    
    ShowBanner --> Tracking: Accept
    ShowBanner --> Disabled: Decline
    
    Tracking --> DataCollection
    DataCollection --> Anonymize
    Anonymize --> PostHog
    
    Disabled --> [*]
    PostHog --> [*]

📊 Mermaid Diagram Support

10+ diagram types with GitHub Pages compatibility:

📓 Jupyter Notebook Support

Seamless integration for data science and computational content:

• Automatic Conversion: .ipynb → Markdown with front matter
• Output Rendering: Code execution results, plots, tables preserved
• Image Extraction: Matplotlib/PNG outputs → /assets/images/notebooks/
• GitHub Actions: Automated conversion on push to pages/_notebooks/
• MathJax Support: LaTeX equations rendered with $$ syntax
• Syntax Highlighting: Code cells with Rouge highlighting
• Responsive Layout: Mobile-friendly notebook viewer

# Convert notebooks
./scripts/convert-notebooks.sh

# Add to _config.yml
collections:
  notebooks:
    output: true
    permalink: /notebooks/:name/

🧭 Enhanced Navigation System (v0.17.0)

Modern, accessible sidebar navigation with ES6 modular architecture:

• ES6 Navigation Modules: Modular JavaScript with native ES6 imports
• Navbar Hover Dropdowns: Desktop hover support with smooth fade transitions
• Intersection Observer Scroll Spy: 70% reduction in scroll event overhead
• Keyboard Shortcuts: [ and ] for section navigation
• Swipe Gestures: Mobile-friendly left/right edge detection
• Skip-to-Content: Accessibility-first WCAG 2.1 Level AA compliant
• Mobile TOC FAB: Floating action button for table of contents
• Nav Tree Component: Hierarchical YAML navigation rendering

🔍 Site Search (v0.18.0)

Client-side search with modal interface and keyboard shortcuts:

• Keyboard Activation: Press / or Cmd/Ctrl+K to open search
• Real-time Results: Instant search across all content
• JSON Index: Auto-generated search index for fast queries
• Bootstrap Modal: Responsive modal interface

🎨 Dark/Light Mode Toggle

Theme color mode switcher with system preference detection:

• Three Modes: Light, dark, and auto (system preference)
• Persistence: LocalStorage saves user preference
• Smooth Transitions: CSS transitions between themes
• Bootstrap Integration: Uses data-bs-theme attribute

📋 Legal & Compliance Pages (v0.15.0)

Built-in GDPR/CCPA compliant documentation:

• Privacy Policy: Comprehensive data collection transparency
• Terms of Service: Ready-to-customize legal framework
• Cookie Consent: Granular user preference management

📦 Installation Methods

Method 1: AI-Powered Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash

Method 2: Remote Theme (GitHub Pages)

# _config.yml
remote_theme: "bamr87/zer0-mistakes"
plugins:
  - jekyll-remote-theme

Method 3: Fork & Deploy as Your Site

Fork into <your-username>.github.io for a working site in minutes:

1. Go to bamr87/zer0-mistakes → Fork
2. Set repository name to <your-username>.github.io
3. Enable Settings → Pages → Deploy from branch: main
4. Visit https://<your-username>.github.io

Then personalize locally:

git clone https://github.com/<your-username>/<your-username>.github.io.git
cd <your-username>.github.io
./scripts/fork-cleanup.sh   # interactive config wizard
docker-compose up

See docs/FORKING.md for the full progressive workflow.

Method 4: Ruby Gem

# Gemfile
gem "jekyll-theme-zer0", "~> 0.21"

📁 Project Structure

graph TD
    ROOT[zer0-mistakes/] --> CONFIG[Configuration]
    ROOT --> THEME[Theme Components]
    ROOT --> CONTENT[Content]
    ROOT --> AUTOMATION[Automation]
    
    CONFIG --> CFG1[_config.yml]
    CONFIG --> CFG2[_config_dev.yml]
    CONFIG --> CFG3[docker-compose.yml]
    
    THEME --> LAYOUTS[_layouts/]
    THEME --> INCLUDES[_includes/]
    THEME --> SASS[_sass/]
    THEME --> ASSETS[assets/]
    
    CONTENT --> PAGES[pages/]
    CONTENT --> DATA[_data/]
    CONTENT --> DOCS[docs/]
    
    AUTOMATION --> SCRIPTS[scripts/]
    AUTOMATION --> TESTS[test/]
    AUTOMATION --> WORKFLOWS[.github/workflows/]
    
    style ROOT fill:#e8f5e9
    style CONFIG fill:#e3f2fd
    style THEME fill:#fff3e0
    style CONTENT fill:#fce4ec
    style AUTOMATION fill:#f3e5f5

Key Directories

�️ Migration Utility

Add the admin settings UI to an existing consumer site using the migration script:

# From the zer0-mistakes repo — install into another site
./scripts/migrate.sh /path/to/your-site

# Preview without making changes
./scripts/migrate.sh --dry-run /path/to/your-site

# Overwrite existing admin pages
./scripts/migrate.sh --force /path/to/your-site

# Verify an existing installation
./scripts/migrate.sh --verify /path/to/your-site

This installs 6 admin pages to pages/_about/settings/:

Note: Admin pages require theme version ≥ 0.22.10 for the admin layout and component includes.

�🔄 Development Workflow

gitGraph
    commit id: "Clone/Install"
    branch feature
    checkout feature
    commit id: "Make Changes"
    commit id: "Test Locally"
    checkout main
    merge feature id: "PR Merged"
    commit id: "Auto Version" type: HIGHLIGHT
    commit id: "Gem Published"
    commit id: "GitHub Release"

Daily Development

# Start development server
docker-compose up

# Make changes (auto-reload enabled)
# Edit files in _layouts/, _includes/, pages/

# Run tests
./test/test_runner.sh

# Commit changes
git commit -m "feat: add new component"

Testing Commands

# Quick validation
./test/validate_installation.sh

# Full test suite
./test/test_runner.sh --verbose

# Docker-specific tests
./test/test_docker_deployment.sh

# Visual / styling checks (Playwright; optional BASE_URL if site already running)
npm run test:styling

Vendor assets (maintainers)

Third-party CSS and JavaScript live under assets/vendor/ so GitHub Pages builds work without npm at publish time. To refresh bundles after changing versions, see Vendor assets (published at /docs/development/vendor-assets/). Short version:

npm install
npm run vendor:install    # manifest downloads (+ Mermaid copy when node_modules present)
# or: ./scripts/vendor-install.sh

🚀 Deployment

GitHub Pages (User Site — Recommended)

Fork the repo as <your-username>.github.io and enable GitHub Pages:

1. Push to main branch
2. GitHub Pages builds automatically
3. Site deploys to https://<your-username>.github.io

No workflows or baseurl configuration needed. See docs/FORKING.md for details.

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant Pages as GitHub Pages
    
    Dev->>GH: git push main
    GH->>Pages: Auto-build Jekyll
    Pages-->>Dev: 🌐 Site live at username.github.io

Docker Production

docker-compose -f docker-compose.prod.yml up -d

Custom Hosting

# Build static site
docker-compose run --rm jekyll jekyll build

# Deploy _site/ to any static host

📚 Documentation

Documentation Architecture

graph LR
    subgraph Technical["📋 /docs/"]
        SYS[systems/]
        FEAT[features/]
        REL[releases/]
    end
    
    subgraph Public["📖 /pages/_docs/"]
        GUIDES[User Guides]
        TUTORIALS[Tutorials]
        REF[Reference]
    end
    
    subgraph AI["🤖 .github/"]
        COPILOT[copilot-instructions.md]
        SEED[seed/]
        INSTR[instructions/]
    end
    
    Technical -->|Process| Public
    AI -->|Guides| Technical
    
    style Technical fill:#e3f2fd
    style Public fill:#e8f5e9
    style AI fill:#fff3e0

Quick Links

🔧 Release System

Automated Release Pipeline

flowchart LR
    subgraph Trigger["🎯 Trigger"]
        COMMIT[Commit to main]
    end
    
    subgraph Analyze["🔍 Analyze"]
        PARSE[Parse Commits]
        BUMP[Determine Version]
    end
    
    subgraph Build["⚙️ Build"]
        CHANGE[Update CHANGELOG]
        VERSION[Bump Version]
        TEST[Run Tests]
        GEM[Build Gem]
    end
    
    subgraph Publish["🚀 Publish"]
        RUBYGEMS[Push to RubyGems]
        GHREL[GitHub Release]
        TAG[Git Tag]
    end
    
    COMMIT --> PARSE --> BUMP
    BUMP --> CHANGE --> VERSION --> TEST --> GEM
    GEM --> RUBYGEMS --> GHREL --> TAG

Release Commands

# Preview release
bash scripts/release patch --dry-run

# Full release
bash scripts/release patch  # 0.21.5 → 0.21.6
bash scripts/release minor  # 0.21.5 → 0.22.0
bash scripts/release major  # 0.21.5 → 1.0.0

⚙️ GitHub Actions Automation

zer0-mistakes ships with a complete CI/CD and automation suite powered by GitHub Actions. Every workflow is opinionated, tested, and ready to fork — push to main and the entire pipeline (test → version → publish → release) runs automatically.

Workflow Catalogue

All workflows live under .github/workflows/.

💡 GitHub Pages adds an additional managed pages-build-deployment run on every push to main.

Pipeline Topology

flowchart LR
    subgraph Devloop["🧑‍💻 Developer Loop"]
        PR[Pull Request]
        PUSH[Push to main]
    end

    subgraph Continuous["🧪 Continuous Integration"]
        CI[ci.yml<br/>Comprehensive CI]
        CODEQL[codeql.yml<br/>Security Scan]
        TESTLATEST[test-latest.yml<br/>Latest Deps]
    end

    subgraph Maintenance["🔧 Maintenance"]
        DEPS[update-dependencies.yml<br/>Weekly Bump]
        ROADMAP[roadmap-sync.yml<br/>README Sync]
        NOTEBOOKS[convert-notebooks.yml<br/>.ipynb → .md]
    end

    subgraph Releaseflow["🚀 Release Pipeline"]
        BUMP[version-bump.yml<br/>Semantic Bump]
        RELEASE[release.yml<br/>Gem + GitHub Release]
        PAGES[pages-build-deployment<br/>GitHub Pages]
    end

    subgraph Bootstrap["🌱 Bootstrap"]
        SETUP[setup-template.yml<br/>New Site Setup]
    end

    PR --> CI
    PR --> CODEQL
    PUSH --> CI
    PUSH --> CODEQL
    PUSH --> ROADMAP
    PUSH --> NOTEBOOKS
    PUSH --> BUMP
    BUMP -->|tag v*| RELEASE
    PUSH --> PAGES
    DEPS -.->|opens PR| PR
    SETUP -.->|first push| PR

    style Continuous fill:#e3f2fd
    style Maintenance fill:#fff3e0
    style Releaseflow fill:#e8f5e9
    style Bootstrap fill:#f3e5f5

What it looks like

🗂 Actions overview — every workflow at a glance

The Actions tab gives you a real-time activity feed — every push to main triggers a coordinated set of workflows that you can audit, re-run, or dispatch manually.

🚀 Release pipeline — automated gem + GitHub release

A single tag (v0.22.21) — or one click on Run workflow — runs the entire publish pipeline in under two minutes. The job graph makes the dependency chain visible: validate → build → publish to RubyGems → cut the GitHub Release. No manual gem push, no manual changelog edit, no missed step.

🧪 Comprehensive CI — parallel quality gates

CI fans out across change detection → fast checks → quality control → matrix test suite → integration tests → build & validate, with annotations surfacing test failures and deprecations directly in the run summary.

🚦 Per-workflow run history

Each workflow has its own run history with branch filters, status badges, and per-job durations — easy to spot regressions or compare runs across branches.

Trigger guide

Use these to invoke automation without leaving your terminal:

# List recent workflow runs
gh run list --repo bamr87/zer0-mistakes --limit 10

# Manually dispatch a release
gh workflow run release.yml --ref main -f tag=v0.22.21

# Trigger an automatic version bump on demand
gh workflow run version-bump.yml --ref main

# Re-run the most recent failed CI run
gh run rerun --failed --repo bamr87/zer0-mistakes

# Watch a workflow run live
gh run watch --repo bamr87/zer0-mistakes

Forking these workflows

When you fork the theme as a starter, the workflows come with you. To make them safe and useful in your fork:

1. Add RUBYGEMS_API_KEY in Settings → Secrets and variables → Actions if you plan to publish your own gem; otherwise disable release.yml.
2. Tune triggers in update-dependencies.yml (default: weekly).
3. Disable setup-template.yml after the first run — it’s a one-shot bootstrap.
4. GitHub Pages is auto-enabled when you push to main if your repo is <username>.github.io.

📸 Screenshots above are real runs captured from github.com/bamr87/zer0-mistakes/actions. Re-capture them for your fork by running ./scripts/test/capture-workflow-screenshots.sh (or just take fresh screenshots) and replacing the files in docs/images/workflows/.

🗺 Roadmap

The diagram and table below are auto-generated from _data/roadmap.yml by scripts/generate-roadmap.sh. See the full Roadmap page for per-version detail and the PRD for product context.

gantt
    title zer0-mistakes Roadmap
    dateFormat YYYY-MM
    section Completed
    v0.17 ES6 Navigation         :done, 2025-12, 2025-12
    v0.18 Site Search            :done, 2026-01, 2026-01
    v0.19 Feature Discovery      :done, 2026-01, 2026-01
    v0.20 Navigation Redesign    :done, 2026-02, 2026-02
    v0.21 Env Switcher           :done, 2026-02, 2026-03
    section Current
    v0.22 AIEO & Customization   :active, 2026-03, 2026-04
    section Future
    v0.23 CMS Integration        :2026-05, 2026-07
    v0.24 i18n Support           :2026-07, 2026-09
    v0.25 Advanced Analytics     :2026-09, 2026-11
    v1.0 Stable Release          :milestone, 2027-01, 1d

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

flowchart LR
    FORK[Fork Repo] --> BRANCH[Create Branch]
    BRANCH --> CODE[Make Changes]
    CODE --> TEST[Run Tests]
    TEST --> PR[Open PR]
    PR --> REVIEW[Code Review]
    REVIEW --> MERGE[Merge! 🎉]
    
    style MERGE fill:#c8e6c9

Quick Contribution

# Fork and clone
gh repo fork bamr87/zer0-mistakes --clone
cd zer0-mistakes

# Create feature branch
git checkout -b feature/awesome-feature

# Make changes and test
docker-compose up
./test/test_runner.sh

# Submit PR
git push origin feature/awesome-feature

📞 Support

📊 Project Stats

🤖 AIEO-Optimized — Built for AI Citation

This site implements AI Engine Optimization (AIEO) to maximize accuracy and depth when AI models cite or summarize its content. Key patterns applied:

All AIEO enhancements are backward-compatible, follow existing code style (Bootstrap 5.3, Liquid templates), and add zero runtime overhead on pages that don’t use them.

🙏 Acknowledgments

Built with these amazing technologies:

• Jekyll — Static site generation
• Bootstrap — UI framework
• Docker — Containerization
• PostHog — Privacy-first analytics
• Mermaid — Diagram rendering

And these AI partners that make zer0-mistakes truly AI-native:

• GitHub Copilot — Project-wide instructions & file-scoped guidance
• OpenAI Codex — Cross-tool agent integration via AGENTS.md
• Cursor — Slash-command workflows in .cursor/commands/
• Claude Code — Anthropic agent compatibility
• Aider, Continue, Jules — Additional agents.md-aware tools
• OpenAI Images API — AI-generated preview images

Built with ❤️ — and a little help from our AI partners — for the Jekyll community

v0.22.21 • Changelog • License • Contributing • AI Agent Guide