jekyll-theme-zer0 0.2.0 → 0.4.0

data/README.md

@@ -3,585 +3,623 @@ title: zer0-mistakes
 sub-title: Jekyll Theme
 description: Docker-optimized Jekyll theme with AI-powered installation automation and comprehensive error handling.
 version: 2.0.0
+layout: default
 tags:
   - jekyll
   - docker
-  - automation
-  - ai-powered
-  - error-handling
+  - remote-theme
+  - github-pages
 categories:
-  - bootstrap
-  - quickstart
+  - jekyll-theme
   - docker
+  - bootstrap
 created: 2024-02-10T23:51:11.480Z
-lastmod: 2025-07-03T12:00:00.000Z
+lastmod: 2025-09-21T12:00:00.000Z
 draft: false
-sidebar:
-  nav: dynamic
 permalink: /zer0/
 slug: zer0
 keywords:
   - jekyll
   - docker
-  - automation
-  - installation
-date: 2025-07-03T12:00:00.000Z
-snippet: Jekyll theme installation with Docker optimization
+  - remote-theme
+  - github-pages
+date: 2025-09-21T12:00:00.000Z
+snippet: Docker-first Jekyll theme with remote theme support
 comments: true
 preview: /images/zer0-mistakes-docker.png
 ---
 
 [![pages-build-deployment](https://github.com/bamr87/zer0-mistakes/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/bamr87/zer0-mistakes/actions/workflows/pages/pages-build-deployment)
-
 [![Gem Version](https://badge.fury.io/rb/jekyll-theme-zer0.svg)](https://badge.fury.io/rb/jekyll-theme-zer0)
+[![CI](https://github.com/bamr87/zer0-mistakes/actions/workflows/ci.yml/badge.svg)](https://github.com/bamr87/zer0-mistakes/actions/workflows/ci.yml)
+[![Auto Version Bump](https://github.com/bamr87/zer0-mistakes/actions/workflows/auto-version-bump.yml/badge.svg)](https://github.com/bamr87/zer0-mistakes/actions/workflows/auto-version-bump.yml)
+[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://github.com/bamr87/zer0-mistakes/blob/main/docker-compose.yml)
+
+# 🚀 zer0-mistakes Jekyll Theme
 
-# 🌱 Jekyll Theme Seed
+**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.
 
-This is a **Docker-optimized Jekyll theme** with AI-powered installation automation, and comprehensive error handling. It embodies IT-Journey principles of Design for Failure (DFF), Don't Repeat Yourself (DRY), Keep It Simple (KIS), and AI-Powered Development (AIPD).
+> **🎯 95% installation success rate** • **⚡ 2-5 minute setup** • **🐳 Universal Docker compatibility** • **🤖 AI-powered error recovery** • **🚀 Automated releases with semantic versioning**
 
 ## 🚀 Quick Start
 
-### Option 1: One-Line Installation (Recommended)
+### ⚡ One-Line Installation (Recommended)
+
+**Get started in under 5 minutes with AI-powered setup:**
 
 ```bash
+# 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
-```
-
-### Option 2: Manual Installation
 
-```bash
-gh repo clone bamr87/zer0-mistakes
-cd zer0-mistakes
+# Start development immediately
 docker-compose up
+# Visit: http://localhost:4000
 ```
 
-## ✨ What Makes This Special
+**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
 
-### 🐳 **Docker-First Approach**
+### 🔧 Manual Installation Options
 
-- **Cross-Platform Compatibility** - Works on Apple Silicon, Intel, and Linux
-- **Zero Configuration** - Automatic environment setup and optimization
-- **Port Standardization** - Consistent localhost:4000 across all environments
-- **Platform Isolation** - No local Ruby/Jekyll installation required
+<details>
+<summary>Click to expand manual installation methods</summary>
 
-### 🛡️ **Self-Healing Installation**
+#### Method 1: GitHub Remote Theme
+Perfect for GitHub Pages hosting:
 
-- **Error Detection** - Automatically identifies and fixes common issues
-- **Content Protection** - Safely handles missing dependencies and broken includes
-- **Configuration Optimization** - Creates Docker-compatible development settings
-- **Comprehensive Documentation** - Auto-generates troubleshooting guides
+```bash
+# Add to your _config.yml
+remote_theme: "bamr87/zer0-mistakes"
 
-### 🧬 **AI-Enhanced Error Handling**
+# Add to your Gemfile
+gem "jekyll-remote-theme"
+```
 
-- **Predictive Problem Resolution** - Fixes issues before they cause failures
-- **Context-Aware Configuration** - Adapts to different project structures
-- **Intelligent Fallbacks** - Graceful degradation when components are unavailable
-- **Learning System** - Improves based on common installation patterns
+#### Method 2: Fork & Customize
+For extensive theme development:
 
-## 🚀 Core Features
+```bash
+# Fork on GitHub, then clone
+gh repo fork bamr87/zer0-mistakes --clone
+cd zer0-mistakes
 
-### Installation Automation
+# Start development
+docker-compose up
+```
+
+#### Method 3: Local Installation
+Install from local repository:
 
 ```bash
-# Installs and configures everything automatically
-curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
+# Clone the repository
+git clone https://github.com/bamr87/zer0-mistakes.git
+cd zer0-mistakes
 
-# Results in working Docker environment:
-docker-compose up  # Just works!
+# Install to new directory
+./install.sh ../my-new-site
+cd ../my-new-site
+docker-compose up
 ```
 
-### Error Prevention
+</details>
 
-- **Theme Dependency Resolution** - Handles missing gem themes
-- **Include File Protection** - Comments out problematic script includes  
-- **Plugin Management** - Ensures essential Jekyll plugins are configured
-- **Docker Optimization** - Creates container-friendly configurations
+## ✨ What Makes This Special
 
-### Development Experience
+### 🤖 **AI-Powered Intelligence**
 
-- **2-5 minute setup** - From zero to running site
-- **95%+ success rate** - Reliable installation across environments
-- **Comprehensive troubleshooting** - Self-documenting error solutions
-- **Zero manual configuration** - Automated optimization for common scenarios
+- **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
 
-## 📊 Evolution Metrics
+### 🐳 **Docker-First Development**
 
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Build Success Rate | ~60% | ~95% | +58% |
-| Setup Time | 15-30 min | 2-5 min | -80% |
-| Docker Compatibility | Limited | Universal | +100% |
-| Error Recovery | Manual | Automatic | +100% |
+- **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
 
-## Prerequisites
+### 🎨 **Modern Design System**
 
-### Required Tools
+- **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
 
-- **Docker** - For containerized development environment
-- **Git** - For repository management
-- **curl** - For one-line installation (or manual download)
+### 🌐 **Deployment Ready**
 
-```shell
-# Confirm your system information
+- **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
 
-system_profiler SPHardwareDataType | awk '/Model Name:|Model Identifier:|Model Number:|Chip:|System Firmware Version:/ {print $0}'
-system_profiler SPSoftwareDataType | awk '/System Version:|Kernel Version:/ {print $0}'
+### 🤖 **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
 
-## Prerequisites
-
-Before we begin, make sure you have the following software installed on your machine:
-
-- [VS code](https://code.visualstudio.com/) installed on your machine (if you're smart)
-- [docker](https://docs.docker.com/get-docker/) installed on your machine (if you're a pro)
-- [homebrew](https://brew.sh/) installed on your machine (if you're a cli junkie)
-- [git](https://git-scm.com/) installed on your machine (if you want to track the truth)
-- [gh cli](https://cli.github.com/) installed on your machine (if you want to publish the truth)
-
-For step-by-step instructions on how to install these tools, visit the "Quickstart" section of the site here: [Quickstart](/quickstart)
-
-To use these tools effectively, you need:
-
-- A GitHub account and a repository where you want to maintain and publish your site.
-- A personal access token from GitHub to authenticate with the GitHub API.
-- A cup of coffee or your favorite beverage to keep you energized.
-- A positive attitude and a sense of curiosity.
-- A sense of adventure and a willingness to explore new tools and technologies.
-- A growth mindset and a willingness to embrace challenges and learn from mistakes.
-- A sense of humor and the ability to laugh at unexpected errors and bugs.
-- A supportive community or network of friends and colleagues to ask for help and share your progress.
-- A clear goal and motivation to build this project and share your knowledge with the world.
-- A spirit of creativity and a desire to express yourself through code and technology.
-
-More importantly, you need to:
-
-- Embrace responsibility and ethical, inclusive software development.
-- Cultivate empathy and create tools that benefit others.
-- Appreciate opportunities and resources for learning and growth.
-- Foster curiosity about AI and machine learning.
-- Pursue a purpose that enhances productivity and creativity.
-- Persevere through challenges with determination.
-- Learn from others and share knowledge with humility.
-- Believe in technology's potential to improve lives and create positive change.
-- Make the learning process fun and engaging.
-- Balance work with breaks for well-being.
-- Celebrate achievements and share your work with the world.
-- Anticipate making a difference in the developer community.
-- Find satisfaction and fulfillment in creating value for others.
-- Connect with the global community of developers and creators.
-- Believe in your ability to create something meaningful and impactful.
-- Stand in awe of technology's power to transform ideas into reality.
-
-## Confirm Prerequisites
-
-Make sure you have the following installed on your machine:
-
-```shell
-# Check if git is installed
-if ! git --version > /dev/null 2>&1; then
-  echo "git is not installed. Installing..."
-  brew install git
-else
-  echo "git is already installed."
-fi
-
-# Check if gh is installed
-if ! gh --version > /dev/null 2>&1; then
-  echo "gh is not installed. Installing..."
-  brew install gh
-else
-  echo "gh is already installed."
-fi
-
-# Check if gh is authenticated
-if ! gh auth status > /dev/null 2>&1; then
-  echo "gh is not authenticated. Please authenticate..."
-  gh auth login
-else
-  echo "gh is already authenticated."
-fi
-
-# Check if Docker is installed
-if ! docker --version > /dev/null 2>&1; then
-  echo "Docker is not installed. Installing..."
-  brew install --cask docker
-else
-  echo "Docker is already installed."
-fi
-
-# Check if Visual Studio Code is installed
-if ! code --version > /dev/null 2>&1; then
-  echo "Visual Studio Code is not installed. Installing..."
-  brew install --cask visual-studio-code
-else
-  echo "Visual Studio Code is already installed."
-fi
-```
+> 📖 **Learn more**: [Automated Version System Documentation](AUTOMATED_VERSION_SYSTEM.md)
 
-## Installation
+### 📊 **Mermaid Diagram Integration** *(New in v0.3.0)*
 
-The zer0-mistakes Jekyll theme can be installed in any repository using the included installation script. This script copies all essential theme files and creates the proper directory structure.
+- **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
 
-### Quick Installation
+> 📖 **Learn more**: [Mermaid Documentation](/docs/jekyll/mermaid/) • [Integration Tutorial](/docs/jekyll/jekyll-diagram-with-mermaid/) • [Test Suite](/docs/jekyll/mermaid-test-suite/)
 
-```bash
-# Clone this repository
-git clone https://github.com/bamr87/zer0-mistakes.git
-cd zer0-mistakes
+## 📋 Prerequisites
+
+Before you begin, ensure you have:
+
+- **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop) (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
 
-# Install the theme in a new directory
-./install.sh my-new-site
+## 🎯 Remote Theme Setup
 
-# Or install in current directory
-./install.sh .
+### Step 1: Create Your Site Repository
+
+```bash
+# Create new repository
+mkdir my-awesome-site
+cd my-awesome-site
+git init
 ```
 
-### What Gets Installed
+### Step 2: Add Remote Theme Configuration
 
-The installation script copies the following essential files:
+Create `_config.yml`:
 
-**Configuration Files:**
+```yaml
+# 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
 
-- `_config.yml` - Main Jekyll configuration
-- `_config_dev.yml` - Development configuration  
-- `frontmatter.json` - VS Code frontmatter configuration
+Create `_config_dev.yml` for local development:
+
+```yaml
+# 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
+```
 
-**Build & Dependency Files:**
+### Step 4: Create Docker Environment
 
-- `Gemfile` - Ruby dependencies
-- `Rakefile` - Build tasks
-- `package.json` - Node.js dependencies
+Create `docker-compose.yml`:
 
-**Docker Files:**
+```yaml
+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
+```
 
-- `docker-compose.yml` - Multi-container setup
-- `Dockerfile` - Container configuration
+### Step 5: Add Essential Files
 
-**Theme Directories:**
+Create `Gemfile`:
 
-- `_data/` - Site data files and navigation
-- `_sass/` - Sass stylesheets and custom styles
-- `_includes/` - Reusable template components
-- `_layouts/` - Page layout templates  
-- `assets/` - Static assets (CSS, JS, images)
+```ruby
+source "https://rubygems.org"
 
-**Static Files:**
+gem "github-pages", group: :jekyll_plugins
+gem "jekyll-remote-theme"
 
-- `404.html` - Custom error page
-- `favicon.ico` - Site icon
-- `index.md` - Homepage (only if not exists)
+group :jekyll_plugins do
+  gem "jekyll-feed"
+  gem "jekyll-sitemap"
+  gem "jekyll-seo-tag"
+  gem "jekyll-paginate"
+end
+```
 
-**Additional Files:**
+Create `index.md`:
 
-- `.gitignore` - Git ignore rules (only if not exists)
-- `INSTALLATION.md` - Setup instructions
+```markdown
+---
+layout: home
+title: Home
+---
 
-### Installation Options
+# Welcome to Your Site
 
-```bash
-# Show help and usage information
-./install.sh --help
+Your content goes here. This theme provides a solid foundation
+for your Jekyll site with Bootstrap 5 styling and Docker development.
+```
 
-# Install in current directory
-./install.sh
+### Step 6: Start Development
 
-# Install in a specific directory
-./install.sh /path/to/my-site
+```bash
+# Start the development server
+docker-compose up
 
-# Install in a relative directory
-./install.sh ../my-new-site
+# Your site will be available at http://localhost:4000
 ```
 
-### After Installation
+## 🚢 Deployment Options
 
-Once installed, navigate to your new site directory and start developing:
+### GitHub Pages (Automatic)
 
-```bash
-cd my-new-site
+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
 
-# Using Docker (recommended)
-docker-compose up
+### Manual Deployment
 
-# Or using local Ruby environment
-bundle install
-bundle exec jekyll serve --config _config_dev.yml
+```bash
+# Build production site
+docker-compose run --rm jekyll jekyll build --config "_config.yml"
 
-# Your site will be available at http://localhost:4000
+# Deploy the _site directory to your hosting provider
 ```
 
-### Customization
+## 📦 Installation Script Features
 
-After installation:
+The automated installation script provides:
 
-1. **Edit Configuration:** Update `_config.yml` with your site details
-2. **Customize Styles:** Modify `_sass/custom.scss` for custom styling
-3. **Add Content:** Create pages in the `pages/` directory
-4. **Update Navigation:** Edit `_data/navigation/` files for site navigation
+- **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
 
-For detailed setup instructions, see the `INSTALLATION.md` file created during installation.
+## 🔧 Prerequisites
 
-## Environment
+### Required Software
 
-### Set your own environment variables
+- **Docker** - For containerized development
+- **Git** - For version control
+- **Text Editor** - VS Code recommended
 
-{% if site.level == 'her0' %}
-  {% include zer0-env-var.html %}
-{% endif %}
+### Installation Commands
 
-### Set the default environment variables
+```bash
+# Install Docker (macOS with Homebrew)
+brew install --cask docker
 
-```shell
-# Or use the following to set the environment variables
+# Install Git (if not already installed)
+brew install git
 
-export GITHOME=~/github
-export GHUSER=$(gh api user --jq '.login')
-export GIT_REPO=zer0-mistakes
-export ZREPO=$GITHOME/$GIT_REPO
+# Verify installations
+docker --version
+git --version
 ```
 
-### Add the environment variables to your shell profile (optional)
+## 🎨 Customization
+
+### Theme Structure
+
+```text
+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
+```
 
-```shell
-#open Code to edit your shell profile and copy the environment variables
+### Custom Styling
 
-code ~/.zprofile
-```
+Create `assets/css/custom.css`:
 
-```shell
-# Confirm the environment variables by echoing them
+```css
+/* Your custom styles here */
+:root {
+  --primary-color: #your-color;
+  --secondary-color: #your-secondary;
+}
 
-echo $GITHOME # /Users/bamr87/github
-echo $GHUSER # bamr87
-echo $GIT_REPO # zer0-mistakes
-echo $ZREPO # /Users/bamr87/github/zer0-mistakes
+/* Override theme styles */
+.navbar-brand {
+  color: var(--primary-color) !important;
+}
 ```
 
-### Set your Git email and name
+### Navigation Setup
 
-```shell
-# Set your Git email and name to tag your commits
+Edit `_data/navigation.yml`:
 
-git config --global user.email "$GHUSER@users.noreply.github.com"
-git config --global user.name "$GHUSER"
+```yaml
+main:
+  - title: "Home"
+    url: /
+  - title: "About"
+    url: /about/
+  - title: "Blog"
+    url: /blog/
+  - title: "Contact"
+    url: /contact/
 ```
 
-### Set your GitHub email using ID (optional)
+## 🧪 Testing & Validation
 
-See [here](https://github.com/settings/emails) for details.
+### Quick Health Check
 
-```shell
-# If you didnt already set it in the previous step
-# FIXME: quotes in comments dont work
+After installation, verify everything is working:
 
-echo "What is your Github ID?"
-read GIT_ID
+```bash
+# 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
 ```
 
-```shell
-# Set your email using ID
+### 🔬 Comprehensive Test Suite
 
-git config --global user.email "$GIT_ID+$GHUSER@users.noreply.github.com"
+Our testing framework validates the entire installation and deployment process:
+
+#### Quick Validation (30 seconds)
+```bash
+# Fast validation without Docker
+./test/validate_installation.sh
 ```
 
-```shell
-# confirm your email
+#### Docker Deployment Test (2-3 minutes)
+```bash
+# Test Docker-specific functionality
+./test/test_docker_deployment.sh --verbose
 
-git config -l
+# Keep test site for inspection
+./test/test_docker_deployment.sh --no-cleanup
 ```
 
-## Initialize your new github repository
+#### Complete Installation Test (3-5 minutes)
+```bash
+# Test all installation methods
+./test/test_installation_complete.sh
 
-[gh cli docs](https://cli.github.com/manual/)
+# Skip remote tests for faster execution
+./test/test_installation_complete.sh --skip-remote --verbose
+```
 
-```shell
-# Create your github home directory and repo
+#### End-to-End Deployment Test (5-10 minutes)
+```bash
+# Full deployment workflow validation
+./test/test_deployment_complete.sh
 
-mkdir -p $ZREPO
+# Skip Docker if unavailable
+./test/test_deployment_complete.sh --skip-docker
 ```
 
-```shell
-# Initialize your github repository
+### 🎯 Test Results Interpretation
 
-gh repo create $GIT_REPO --gitignore Jekyll -l mit --public
-```
+**✅ 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
 
-```shell
-# If new repo, initialize it
+**⚠️ 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
 
-cd $ZREPO
-git init
-git remote add origin https://github.com/${GHUSER}/${GIT_REPO}.git
-git pull origin main
-curl https://raw.githubusercontent.com/bamr87/it-journey/master/zer0.md > README.md
-git add README.md
-git commit -m "Init $GIT_REPO"
-git branch -M main
-git push -u origin main
+**❌ 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
 ```
 
-### Checkpoint - Github Repo Initialized
+**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
 
-Go to your new github repository.
+The theme installation and deployment process has been **thoroughly tested and validated** across multiple scenarios.
 
-```shell
-# Open your new github repository in the browser
+## 🛠️ Troubleshooting
 
-open https://github.com/${GHUSER}/${GIT_REPO}
+### Quick Fixes
 
+**🐳 Docker Issues:**
+```bash
+# Restart Docker Desktop
+# Then rebuild containers
+docker-compose down && docker-compose up --build
 ```
 
-<a id="repo-link"></a>
+**⚡ Port Conflicts:**
+```bash
+# Use different port
+docker-compose run -p 4001:4000 jekyll
+```
 
-![Checkpoint 1](/assets/images/zer0-checkpoint-1.png)
+**🍎 Apple Silicon Issues:**
+```bash
+# Force platform if needed
+docker-compose up --build
+# The linux/amd64 platform is already configured
+```
 
-## Initialize Jekyll
+### Common Issues
 
-### Create Gemfile
+#### Docker Container Won't Start
 
-```shell
-# Create a new Gemfile
-cd $ZREPO
-touch Gemfile
+```bash
+# Check Docker is running
+docker ps
 
-# Write the non-commented lines to the Gemfile
-echo 'source "https://rubygems.org"' >> Gemfile
-echo "gem 'github-pages' , '231'" >> Gemfile
-echo "gem 'jekyll' , '3.9.5'" >> Gemfile
-echo "gem 'jekyll-theme-zer0' , '0.1.2'" >> Gemfile
-echo "group :jekyll_plugins do" >> Gemfile
-echo "  gem 'jekyll-feed', \"~> 0.17\"" >> Gemfile
-echo "  gem 'jekyll-sitemap' , \"~> 1.4.0\"" >> Gemfile
-echo "  gem 'jekyll-seo-tag', \"~> 2.8.0\"" >> Gemfile
-echo "  gem 'jekyll-paginate', '~> 1.1'" >> Gemfile
-echo "end" >> Gemfile
+# Rebuild container
+docker-compose down
+docker-compose up --build
 ```
 
-### Configure Jekyll
+#### Theme Not Loading
+
+```bash
+# Verify remote_theme setting in _config.yml
+remote_theme: "bamr87/zer0-mistakes"
 
-```shell
-code _config.yml
+# Check Gemfile includes jekyll-remote-theme
+gem "jekyll-remote-theme"
 ```
 
-```yaml
-theme: jekyll-theme-zer0
+#### Port Already in Use
 
-title: zer0-mistakes
-email: bamr87@zer0-mistakes.com
-description: >- # this means to ignore newlines until "baseurl:"
-  Write an awesome description for your new site here. You can edit this
-  line in _config.yml. It will appear in your document head meta (for
-  Google search results) and in your feed.xml site description.
-baseurl: null # the subpath of your site, e.g. /blog
-url: null # the base hostname & protocol for your site, e.g. http://example.com
-twitter_username: bamr87
-github_username:  bamr87
-```
+```bash
+# Find process using port 4000
+lsof -i :4000
 
-### Create Dockerfile
-
-```shell
-# Create a new Dockerfile
-cd $ZREPO
-touch Dockerfile
-
-# Write the content to the Dockerfile
-echo "# Use an official Ruby runtime as a parent image" >> Dockerfile
-echo "FROM ruby:2.7.4" >> Dockerfile
-echo "# escape=\\" >> Dockerfile
-echo "ENV GITHUB_GEM_VERSION 231" >> Dockerfile
-echo "ENV JSON_GEM_VERSION 1.8.6" >> Dockerfile
-echo "ENV GIT_REPO ${GIT_REPO}" >> Dockerfile
-echo "WORKDIR /app" >> Dockerfile
-echo "ADD . /app" >> Dockerfile
-echo "RUN gem update --system 3.3.22" >> Dockerfile
-echo "RUN bundle update" >> Dockerfile
-echo "RUN bundle install" >> Dockerfile
-echo "RUN bundle clean --force" >> Dockerfile
-echo "EXPOSE 4000" >> Dockerfile
-echo 'CMD ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0"]' >> Dockerfile
+# Or use different port
+docker-compose run -p 4001:4000 jekyll
 ```
 
-```shell
-# build the docker image based on the Dockerfile
-docker build -t ${GIT_REPO} .
-```
+#### GitHub Pages Build Fails
 
-```shell
-# Run the container in detached mode
-docker run -d -p 4000:4000 -v ${ZREPO}:/app --name zer0_container ${GIT_REPO}
+- Ensure `jekyll-remote-theme` plugin is in `_config.yml`
+- Check that all plugins are GitHub Pages compatible
+- Verify `_config.yml` syntax is valid YAML
 
-# Start the container and run the CMD line from the Dockerfile
-docker start zer0_container
+### Development Tips
 
-# Attach to the running container
-docker exec -it zer0_container /bin/bash
-```
+```bash
+# View container logs
+docker-compose logs -f jekyll
 
-## Checkpoint - Jekyll Initialized
+# Clean Jekyll cache
+docker-compose run --rm jekyll jekyll clean
 
-```shell
-open http://localhost:4000/
+# Bundle install in container
+docker-compose run --rm jekyll bundle install
+
+# Access container shell
+docker-compose exec jekyll bash
 ```
 
-![](/assets/images/zer0-checkpoint-2.png)
+## 🤝 Contributing
 
-```shell
-code _config.yml
-```
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
 
-```yaml
-title: zer0-mistakes
-email: bamr87@zer0-mistakes.com
-description: >- # this means to ignore newlines until "baseurl:"
-  Write an awesome description for your new site here. You can edit this
-  line in _config.yml. It will appear in your document head meta (for
-  Google search results) and in your feed.xml site description.
-baseurl: null # the subpath of your site, e.g. /blog
-url: null # the base hostname & protocol for your site, e.g. http://example.com
-twitter_username: bamr87
-github_username:  bamr87
-```
+### Development Setup
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR-USERNAME/zer0-mistakes.git
+cd zer0-mistakes
 
-## Convert zer0.md to zer0.sh using Python
-
-```python
-def convert_md_to_files(md_file_path):
-    language_files = {}
-    language_mode = None
-    language_extensions = {'python': '.py', 'shell': '.sh'}
-    shebang_lines = {'python': '#!/usr/bin/env python3\n', 'shell': '#!/bin/bash\n'}
-
-    with open(md_file_path, 'r') as md_file:
-        for line in md_file:
-            if line.startswith('```'):
-                if language_mode:
-                    # End of a language block, switch back to markdown mode
-                    language_mode = None
-                else:
-                    # Start of a language block, open a new file for this language if not already open
-                    language = line.strip('`\n')
-                    if language in language_extensions:
-                        language_mode = language
-                        if language not in language_files:
-                            language_file = open(md_file_path.replace('.md', language_extensions[language]), 'w')
-                            if language in shebang_lines:
-                                language_file.write(shebang_lines[language])
-                            language_files[language] = language_file
-                continue
-
-            if language_mode:
-                language_files[language_mode].write(line)
-
-    # Close all open language files
-    for language_file in language_files.values():
-        language_file.close()
-
-convert_md_to_files('zer0.md')
+# 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
 ```
 
-## Config file
+## 📄 License
 
-```yaml
-{% include_relative _config.yml %}
-```
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [Jekyll](https://jekyllrb.com/) static site generator
+- Styled with [Bootstrap 5](https://getbootstrap.com/) framework
+- Containerized with [Docker](https://docker.com/) for consistent development
+- Inspired by IT-Journey principles of reliable, self-healing software
+
+## 📞 Support
+
+- **Documentation**: [Theme Documentation](https://bamr87.github.io/zer0-mistakes/)
+- **Issues**: [GitHub Issues](https://github.com/bamr87/zer0-mistakes/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/bamr87/zer0-mistakes/discussions)
+- **Email**: [support@zer0-mistakes.com](mailto:support@zer0-mistakes.com)
+
+---
+
+Built with ❤️ for the Jekyll community