🚀 zer0-mistakes Jekyll Theme

Professional Jekyll theme with AI-powered installation, Docker-first development, automated release management, and VS Code Copilot optimization. Built for developers who value reliability, modern workflows, AI-assisted development, and zero-configuration setup.

🎯 95% installation success rate • ⚡ 2-5 minute setup • 🐳 Universal Docker compatibility • 🤖 AI-powered error recovery • 🚀 Automated releases with semantic versioning • 💡 VS Code Copilot optimized

🚀 Quick Start

⚡ One-Line Installation (Recommended)

Get started in under 5 minutes with AI-powered setup:

# Create new site with intelligent installation
mkdir my-awesome-site && cd my-awesome-site
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash

# Start development immediately
docker-compose up
# Visit: http://localhost:4000

What this does automatically:

• ✅ Detects your platform (Apple Silicon, Intel, Linux)
• ✅ Downloads and configures all theme files
• ✅ Sets up Docker development environment
• ✅ Creates optimized configurations
• ✅ Handles errors and provides solutions

🔧 Manual Installation Options

✨ What Makes This Special

🤖 AI-Powered Intelligence & VS Code Copilot Integration

• Smart Error Detection - Automatically identifies and fixes common Jekyll issues
• Platform Optimization - Detects Apple Silicon, Intel, and Linux configurations
• Self-Healing Setup - Recovers from installation failures automatically
• Intelligent Diagnostics - Provides actionable solutions for problems
• VS Code Copilot Optimized - Structured for enhanced AI-assisted development
• AI Development Workflows - Built-in patterns for maximum AI productivity

🐳 Docker-First Development

• Universal Compatibility - Works identically on all platforms
• Zero Local Dependencies - No Ruby/Jekyll installation required
• Instant Setup - docker-compose up and you’re running
• Isolated Environment - No conflicts with other projects

🎨 Modern Design System

• Bootstrap 5.3 - Latest responsive framework with dark mode
• Professional Layouts - Blog, landing, documentation, and collection templates
• SEO Optimized - Built-in meta tags, structured data, and social sharing
• Performance Focused - Optimized loading, caching, and Core Web Vitals

📊 Privacy-First Analytics & Tracking

• PostHog Integration - Advanced analytics with privacy controls and GDPR/CCPA compliance
• Cookie Consent Management - Granular user permissions with persistent preferences
• Custom Event Tracking - Jekyll-specific events (downloads, navigation, reading engagement)
• Development Safety - Analytics disabled in development environment
• User Privacy Controls - Respect Do Not Track, opt-out mechanisms, data anonymization
• Comprehensive Insights - Page views, user journeys, content engagement, and performance metrics

🌐 Deployment Ready

• GitHub Pages - Zero-config deployment with remote theme
• Azure Static Web Apps - Pre-configured CI/CD workflows
• Custom Domains - SSL/TLS and CDN ready
• Multiple Hosting - Works with Netlify, Vercel, and custom servers

🤖 Automated Release Management

• Smart Version Bumping - Analyzes commits and automatically increments versions
• Conventional Commits - Follows semantic versioning based on commit patterns
• Automated Changelogs - Generates release notes from commit history
• RubyGems Publishing - Automatically publishes gem releases
• GitHub Releases - Creates comprehensive release pages with assets
• CI/CD Integration - Seamless automation with GitHub Actions

ℹ️ Automatic Theme Version Display

• Zero Configuration - Theme version displays automatically, no hardcoding needed
• System Information - Shows Jekyll, Ruby, and build environment details
• Always Accessible - Info modal available from header (⚙️) and footer on every page
• Dynamic Extraction - Version pulled from gem specification during build
• Comprehensive Details - Lists active plugins, technology stack, and helpful links
• GitHub Pages Compatible - Works with both local gems and remote themes

Learn more about the Theme Version Feature →

📖 Learn more: Automated Version System Documentation

📊 Mermaid Diagram Integration (New in v0.3.0)

• Complete Diagram Support - Flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, git graphs, journey diagrams, and mindmaps
• GitHub Pages Compatible - Works seamlessly with both local development and GitHub Pages deployment
• Conditional Loading - Only loads Mermaid when needed, optimizing performance
• Responsive Design - Diagrams automatically scale across all devices
• Dark Mode Support - Forest theme optimized for dark mode compatibility
• Comprehensive Documentation - Complete user guide with live examples and troubleshooting
• Automated Testing - 16 automated tests covering all aspects of functionality

📖 Learn more: Mermaid Documentation • Integration Tutorial • Test Suite

📚 Documentation Architecture

Zer0-Mistakes features a dual documentation structure designed for different audiences and use cases:

🛠️ Technical Documentation → /docs/

Repository-specific technical documentation (MDX format) for developers and contributors:

Key characteristics:

• MDX format with interactive components and rich code examples
• Source code focused with direct references to _layouts/, _includes/, scripts/
• Architecture documentation explaining how features are built and maintained
• Developer workflows including testing, deployment, and contribution guidelines

📖 Public Documentation → /pages/_docs/

Published online documentation (Markdown format) for end-users and general developers:

Key characteristics:

• Markdown format optimized for Jekyll rendering and online consumption
• User-focused content targeting theme adopters and general developers
• Processed content converted from MDX sources and external documentation
• Published online at zer0-mistakes.org/docs

🔄 Content Flow & Conversion

graph LR
    A[Technical Docs<br/>/docs/ *.mdx] --> B[Processing Scripts]
    B --> C[Public Docs<br/>/pages/_docs/ *.md]
    D[External Docs<br/>Jekyll, Bootstrap] --> E[Import Scripts]
    E --> C
    C --> F[Jekyll Build]
    F --> G[Published Site]

Documentation Workflow:

1. Technical implementation documented in /docs/ using MDX for rich content
2. Processing pipeline converts and sanitizes content for public consumption
3. External documentation imported from official sources and integrated
4. Jekyll rendering builds and serves final documentation site

📍 Quick Navigation: Technical Docs • Public Documentation • GitHub Copilot Instructions • Contributing Guidelines

📋 Prerequisites

Before you begin, ensure you have:

• Docker Desktop - Download here (recommended)
• Git - For version control and repository management
• Text Editor - VS Code, Sublime Text, or your preferred editor

Optional but helpful:

• GitHub CLI - For easier repository management
• Ruby 3.0+ - If you prefer local development over Docker

🎯 Remote Theme Setup

Step 1: Create Your Site Repository

# Create new repository
mkdir my-awesome-site
cd my-awesome-site
git init

Step 2: Add Remote Theme Configuration

Create _config.yml:

# Remote theme configuration
remote_theme: "bamr87/zer0-mistakes"

# Site settings
title: Your Site Title
email: your-email@example.com
description: >-
  Your site description here. This will appear in search engines
  and social media previews.

# GitHub Pages configuration
plugins:
  - jekyll-remote-theme
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-paginate

# Build settings
markdown: kramdown
highlighter: rouge
permalink: /:categories/:year/:month/:day/:title/
paginate: 10
paginate_path: "/blog/page:num/"

Step 3: Add Development Configuration

Create _config_dev.yml for local development:

# Development overrides
url: "http://localhost:4000"
baseurl: ""

# Development plugins
plugins:
  - jekyll-remote-theme
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-paginate
  - jekyll-livereload

# Development settings
incremental: true
livereload: true
open_url: true

Step 4: Create Docker Environment

Create docker-compose.yml:

services:
  jekyll:
    image: jekyll/jekyll:latest
    platform: linux/amd64
    command: jekyll serve --watch --force_polling --config "_config.yml,_config_dev.yml" --host 0.0.0.0 --port 4000
    volumes:
      - ./:/app
    ports:
      - "4000:4000"
    working_dir: /app
    environment:
      JEKYLL_ENV: development

Step 5: Add Essential Files

Create Gemfile:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme"

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-sitemap"
  gem "jekyll-seo-tag"
  gem "jekyll-paginate"
end

Create index.md:

---
layout: home
title: Home
---

# Welcome to Your Site

Your content goes here. This theme provides a solid foundation
for your Jekyll site with Bootstrap 5 styling and Docker development.

Step 6: Start Development

# Start the development server
docker-compose up

# Your site will be available at http://localhost:4000

🚢 Deployment Options

GitHub Pages (Automatic)

1. Push your repository to GitHub
2. Go to repository Settings → Pages
3. Select source branch (usually main)
4. Your site will be automatically built and deployed

Manual Deployment

# Build production site
docker-compose run --rm jekyll jekyll build --config "_config.yml"

# Deploy the _site directory to your hosting provider

📦 Installation Script Features

The automated installation script provides:

• Smart Detection - Identifies existing Jekyll sites vs. new setups
• Dependency Resolution - Installs required gems and configurations
• Error Recovery - Fixes common issues automatically
• Docker Setup - Creates optimized Docker Compose environment
• GitHub Pages Prep - Configures for seamless GitHub Pages deployment

🔧 Prerequisites

Required Software

• Docker - For containerized development
• Git - For version control
• Text Editor - VS Code recommended

Installation Commands

# Install Docker (macOS with Homebrew)
brew install --cask docker

# Install Git (if not already installed)
brew install git

# Verify installations
docker --version
git --version

🎨 Customization

Theme Structure

your-site/
├── _config.yml          # Main configuration
├── _config_dev.yml      # Development overrides
├── docker-compose.yml   # Docker environment
├── Gemfile             # Ruby dependencies
├── index.md            # Homepage
├── _data/              # Site data files
├── _posts/             # Blog posts
├── _pages/             # Additional pages
└── assets/             # Images, CSS, JS

Custom Styling

Create assets/css/custom.css:

/* Your custom styles here */
:root {
  --primary-color: #your-color;
  --secondary-color: #your-secondary;
}

/* Override theme styles */
.navbar-brand {
  color: var(--primary-color) !important;
}

Navigation Setup

Edit _data/navigation.yml:

main:
  - title: "Home"
    url: /
  - title: "About"
    url: /about/
  - title: "Blog"
    url: /blog/
  - title: "Contact"
    url: /contact/

🧪 Testing & Validation

Quick Health Check

After installation, verify everything is working:

# 1. Check installation files
ls -la _config.yml docker-compose.yml INSTALLATION.md

# 2. Validate configuration
docker-compose config                  # Should show no errors
ruby -e "require 'yaml'; YAML.load_file('_config.yml')"  # Should load without errors

# 3. Test Docker environment
docker-compose up -d                  # Start in background
sleep 30                              # Wait for Jekyll to start
curl -I http://localhost:4000         # Should return HTTP 200 OK
docker-compose down                   # Stop services

🔬 Comprehensive Test Suite

Our testing framework validates the entire installation and deployment process:

Quick Validation (30 seconds)

# Fast validation without Docker
./test/validate_installation.sh

Docker Deployment Test (2-3 minutes)

# Test Docker-specific functionality
./test/test_docker_deployment.sh --verbose

# Keep test site for inspection
./test/test_docker_deployment.sh --no-cleanup

Complete Installation Test (3-5 minutes)

# Test all installation methods
./test/test_installation_complete.sh

# Skip remote tests for faster execution
./test/test_installation_complete.sh --skip-remote --verbose

End-to-End Deployment Test (5-10 minutes)

# Full deployment workflow validation
./test/test_deployment_complete.sh

# Skip Docker if unavailable
./test/test_deployment_complete.sh --skip-docker

🎯 Test Results Interpretation

✅ Success Indicators:

• HTTP 200 OK response from http://localhost:4000
• Jekyll logs show “Server running… press ctrl-c to stop”
• Site content includes zer0-mistakes theme elements
• Live reload header present (X-Rack-Livereload: 1)
• Build time under 5 seconds

⚠️ Common Issues:

• Port conflicts: Use docker-compose run -p 4001:4000 jekyll
• Volume mounting: Use home directory instead of /tmp
• Bundle install slow: Normal for first run (60-90 seconds)
• Repository errors: Check PAGES_REPO_NWO environment variable

❌ Failure Indicators:

• Gemfile contains gemspec (should be site-configured)
• Docker container exits immediately
• _config.yml syntax errors
• Missing theme files or directories

🎉 Validated Test Results

Latest Test Results (September 21, 2025):

✅ Docker Deployment Test: 5/5 tests PASSED (100% success rate)
✅ Installation Process: All files and directories created correctly
✅ Gemfile Configuration: Properly configured for Jekyll sites
✅ Docker Volume Mounting: Working correctly in home directory
✅ Environment Variables: PAGES_REPO_NWO properly configured
✅ Jekyll Build & Serve: Site accessible at http://localhost:4000
✅ Performance: Bundle install ~60s, Jekyll build ~2.3s

Test Environment:

• OS: macOS (Apple Silicon)
• Docker: Available and functional
• Ruby: 2.6.10 (system)
• Jekyll: 3.9.5 (via GitHub Pages gem)
• Build Time: 2.315 seconds
• Bundle Install: 98 gems installed successfully

The theme installation and deployment process has been thoroughly tested and validated across multiple scenarios.

🛠️ Troubleshooting

Quick Fixes

🐳 Docker Issues:

# Restart Docker Desktop
# Then rebuild containers
docker-compose down && docker-compose up --build

⚡ Port Conflicts:

# Use different port
docker-compose run -p 4001:4000 jekyll

🍎 Apple Silicon Issues:

# Force platform if needed
docker-compose up --build
# The linux/amd64 platform is already configured

Common Issues

Docker Container Won’t Start

# Check Docker is running
docker ps

# Rebuild container
docker-compose down
docker-compose up --build

Theme Not Loading

# Verify remote_theme setting in _config.yml
remote_theme: "bamr87/zer0-mistakes"

# Check Gemfile includes jekyll-remote-theme
gem "jekyll-remote-theme"

Port Already in Use

# Find process using port 4000
lsof -i :4000

# Or use different port
docker-compose run -p 4001:4000 jekyll

GitHub Pages Build Fails

• Ensure jekyll-remote-theme plugin is in _config.yml
• Check that all plugins are GitHub Pages compatible
• Verify _config.yml syntax is valid YAML

Development Tips

# View container logs
docker-compose logs -f jekyll

# Clean Jekyll cache
docker-compose run --rm jekyll jekyll clean

# Bundle install in container
docker-compose run --rm jekyll bundle install

# Access container shell
docker-compose exec jekyll bash

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/zer0-mistakes.git
cd zer0-mistakes

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

# Make changes and test
docker-compose up

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

� Documentation

📖 Comprehensive Documentation Center

All documentation is organized in the docs/ directory:

• 📋 Documentation Overview - Complete documentation center with organized structure
• 🚀 Release Documentation - Version history and release notes
• ⭐ Feature Documentation - Detailed feature guides and implementation
• ⚙️ System Documentation - Core systems, automation, and CI/CD
• 🔧 Configuration Guides - Setup and hosting configuration
• 📝 Documentation Templates - Standardized templates for consistent documentation

📊 Recent Releases

• v0.5.0 - Comprehensive Sitemap Integration (Latest)
• v0.4.0 - Statistics Dashboard
• v0.3.0 - Mermaid Integration v2.0

🌟 Key Features

• Sitemap Integration - Unified site navigation and content discovery
• Automated Version System - Intelligent release automation
• CI/CD Pipeline - Comprehensive testing and deployment
• URL Configuration - Multi-hosting setup guide
• GitHub Copilot Instructions - AI-assisted development with comprehensive coding guidelines

�📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Jekyll static site generator
• Styled with Bootstrap 5 framework
• Containerized with Docker for consistent development
• Inspired by IT-Journey principles of reliable, self-healing software

📞 Support

• Documentation: Theme Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@zer0-mistakes.com

Built with ❤️ for the Jekyll community