🚀 zer0-mistakes Jekyll Theme

Professional Jekyll theme with AI-powered installation, Docker-first development, automated release management, and comprehensive error handling. Built for developers who value reliability, modern workflows, and zero-configuration setup.

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

🚀 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

• 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

🐳 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

🌐 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

📖 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

📋 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

📄 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