🚀 zer0-mistakes

The Self-Healing Jekyll Theme

Docker-first • AI-powered • Privacy-compliant • Zero-configuration

Quick Start • Features • Documentation • Contributing

📖 Table of Contents

• Overview
• Quick Start
• Architecture
• Key Features
• Installation Methods
• Project Structure
• Development Workflow
• Deployment
• Documentation
• Release System
• Roadmap
• Contributing
• Support

Overview

zer0-mistakes is a professional Jekyll theme engineered to eliminate setup friction and provide a seamless development experience. With AI-powered error recovery, Docker containerization, and comprehensive automation, you can go from zero to deployed in under 5 minutes.

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 Install Script
    participant Docker
    participant Browser
    
    You->>Install Script: curl ... | bash
    Install Script->>Install Script: Detect platform
    Install Script->>Install Script: Download theme files
    Install Script->>Install Script: Configure Docker
    Install Script-->>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!

🏗 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)" : 30
    "Bootstrap 5.3 (UI)" : 25
    "Docker (Dev Env)" : 20
    "Liquid (Templates)" : 15
    "PostHog (Analytics)" : 10

✨ Key Features

🤖 AI-Powered Installation

The 1,090-line install.sh script provides intelligent error recovery with 27+ automated fix scenarios:

flowchart TD
    START([Start Installation]) --> DETECT[Detect Platform]
    DETECT --> CHECK{Prerequisites OK?}
    
    CHECK -->|Yes| DOWNLOAD[Download Theme]
    CHECK -->|No| FIX[Auto-Fix Issues]
    FIX --> CHECK
    
    DOWNLOAD --> CONFIG[Configure Docker]
    CONFIG --> VALIDATE{Build Success?}
    
    VALIDATE -->|Yes| DONE([✅ Ready!])
    VALIDATE -->|No| DIAGNOSE[Diagnose Error]
    DIAGNOSE --> RECOVER[Apply Fix]
    RECOVER --> VALIDATE
    
    style START fill:#e3f2fd
    style DONE fill:#c8e6c9
    style FIX fill:#fff3e0
    style RECOVER fill:#fff3e0

🐳 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.14.0)

Modern, accessible sidebar navigation with advanced features:

• 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
• Unified Bootstrap Icons: Consistent iconography across all components
• Focus Management: Improved screen reader support with ARIA labels

📋 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 & Customize

gh repo fork bamr87/zer0-mistakes --clone
cd zer0-mistakes
docker-compose up

Method 4: Ruby Gem

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

📁 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

🔄 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

🚀 Deployment

GitHub Pages (Automatic)

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant Actions as GitHub Actions
    participant Pages as GitHub Pages
    
    Dev->>GH: git push main
    GH->>Actions: Trigger workflow
    Actions->>Actions: jekyll build
    Actions->>Pages: Deploy _site/
    Pages-->>Dev: 🌐 Site live!

1. Push to main branch
2. GitHub Actions builds automatically
3. Site deploys to GitHub Pages

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
/opt/homebrew/bin/bash scripts/release patch --dry-run

# Full release
/opt/homebrew/bin/bash scripts/release patch  # 0.15.0 → 0.15.1
/opt/homebrew/bin/bash scripts/release minor  # 0.15.0 → 0.16.0
/opt/homebrew/bin/bash scripts/release major  # 0.15.0 → 1.0.0

🗺 Roadmap

gantt
    title zer0-mistakes Roadmap
    dateFormat YYYY-MM
    section Current
    v0.15.x Maintenance       :done, 2025-12, 2026-01
    section Future
    v0.16 - CMS Integration   :2026-01, 2026-03
    v0.17 - Advanced Analytics:2026-04, 2026-06
    v0.18 - i18n Support      :2026-07, 2026-09
    v1.0 - Production Ready   :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

🙏 Acknowledgments

Built with these amazing technologies:

• Jekyll - Static site generation
• Bootstrap - UI framework
• Docker - Containerization
• PostHog - Privacy-first analytics
• Mermaid - Diagram rendering
• GitHub Copilot - AI assistance

Built with ❤️ for the Jekyll community

v0.15.0 • Changelog • License • Contributing