Skip to main content

Jekyll Setup

By Zer0-Mistakes Development Team

Configure your Docker-first Jekyll development environment. Start the development server, create content, and customize your theme.

Estimated reading time: 28 minutes

Edit on GitHub

🚀 Jekyll Setup - Docker-First Development

Welcome to the modern Jekyll development experience with Zer0-Mistakes! This guide covers everything you need to know about developing Jekyll sites using our Docker-first approach - no Ruby installation required.

🎯 Overview

The Zer0-Mistakes theme embraces a Docker-first development philosophy that eliminates environment inconsistencies and provides a seamless development experience across all platforms. Everything runs in containers, making setup predictable and maintenance-free.

Why Docker-First?

  • ✅ Zero Local Dependencies: No Ruby, gems, or version conflicts
  • ✅ Consistent Environments: Same setup on macOS, Windows, and Linux
  • ✅ Instant Setup: One command starts your development environment
  • ✅ Production Parity: Development matches deployment exactly
  • ✅ Team Collaboration: Everyone has identical setups

🛠️ Prerequisites

Before starting Jekyll development, ensure you have completed:

  1. Machine Setup - Docker Desktop, Git, and VS Code installed
  2. Repository cloned - Either forked or using the install script

🏗️ Jekyll Development Workflow

1. Start Development Environment

Navigate to your theme directory and start the containerized Jekyll server:

# Navigate to your project
cd ~/github/zer0-mistakes

# Start Jekyll development server
docker-compose up

This command:

  • 🐳 Pulls the latest Jekyll Docker image
  • 📦 Installs all Ruby dependencies automatically
  • 🔄 Starts Jekyll server with live reload
  • 🌐 Makes your site available at http://localhost:4000

2. Verify Setup

Open your browser and visit:

  • Local Site: http://localhost:4000
  • Live Reload: Changes automatically refresh the browser

You should see:

✅ Jekyll server running on http://localhost:4000
✅ Live reload enabled
✅ Auto-regeneration: enabled for development

3. Development Commands

Essential Docker Commands

# Start development server (detached mode)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop server
docker-compose down

# Restart with fresh build
docker-compose down && docker-compose up --build

# Access container shell for debugging
docker-compose exec jekyll bash

# Clean and rebuild
docker-compose exec jekyll jekyll clean
docker-compose exec jekyll jekyll build

Jekyll-Specific Commands

# Build site for production
docker-compose exec jekyll jekyll build --config _config.yml

# Run in development mode with drafts
docker-compose exec jekyll jekyll serve --drafts --future

# Check site health
docker-compose exec jekyll jekyll doctor

# Generate new post
docker-compose exec jekyll jekyll post "My New Post Title"

📝 Content Creation

Blog Posts

Create new posts in the pages/_posts/ directory:

# Create new post file
touch pages/_posts/$(date +%Y-%m-%d)-my-awesome-post.md

Use this frontmatter template:

---
title: "My Awesome Post"
description: "Brief description for SEO and social media"
date: 2025-01-27T10:00:00.000Z
preview: /images/previews/jekyll-setup.png
tags: [jekyll, tutorial, web-development]
categories: [Development, Tutorial]
sub-title: "Subtitle for additional context"
excerpt: "One-sentence summary of the post"
author: "Your Name"
layout: journals
keywords:
  primary: ["main keyword", "secondary keyword"]
  secondary: ["supporting terms", "related topics"]
lastmod: 2025-01-27T10:00:00.000Z
permalink: /my-awesome-post/
comments: true
---
# Your Post Content

Write your amazing content here using Markdown!

Static Pages

Create pages in the pages/ directory or root:

---
title: "About"
layout: default
permalink: /about/
description: "Learn more about this site"
---
# About This Site

Your page content here...

Collections (Advanced)

For structured content like tutorials or documentation:

# In _config.yml
collections:
  tutorials:
    output: true
    permalink: /:collection/:name/

🎨 Theme Customization

Configuration Files

The Zer0-Mistakes theme uses layered configuration:

Production Config (_config.yml)

# Core Jekyll settings
title: "Your Site Title"
description: "Your site description"
url: "https://yourdomain.com"
baseurl: ""

# Theme settings
remote_theme: "bamr87/zer0-mistakes"
plugins:
  - jekyll-remote-theme
  - jekyll-sitemap
  - jekyll-seo-tag

# Bootstrap 5 integration
bootstrap:
  version: "5.3.3"
  css_cdn: true
  js_cdn: true

Development Config (_config_dev.yml)

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

# Local theme development
theme: zer0-mistakes
remote_theme: false

# Development settings
livereload: true
incremental: true
show_drafts: true
future: true

Custom Styling

Add custom CSS in assets/css/custom.css:

/* Custom Bootstrap 5 overrides */
:root {
  --bs-primary: #your-color;
  --bs-secondary: #your-secondary-color;
}

/* Custom component styles */
.custom-header {
  background: linear-gradient(135deg, var(--bs-primary), var(--bs-secondary));
}

Layout Customization

Override theme layouts by creating files in _layouts/:

<!-- _layouts/custom.html -->
--- layout: default ---

<div class="container-fluid">
  <div class="row">
    <main class="col-12"><!--
  ===================================================================
  DEFAULT LAYOUT - Standard content layout with sidebars
  ===================================================================
  
  File: default.html
  Path: _layouts/default.html
  Inherits: root.html
  Purpose: Primary content layout with sidebar navigation and table of contents
  
  Template Logic:
  - Creates a responsive three-column layout using Bootstrap grid
  - Left sidebar: Site navigation and content outline (collapsible on mobile)
  - Center: Main content area with page title and body content
  - Right sidebar: Table of contents and page shortcuts (hidden on mobile)
  - Implements scroll spy for navigation highlighting
  - Responsive design that stacks vertically on mobile devices
  
  Layout Structure:
  1. Container wrapper with Bootstrap responsive classes
  2. Left sidebar (bd-sidebar) - Navigation and outline
  3. Main content area (bd-main) with:
     - Intro section (page title, metadata)
     - Right sidebar (bd-toc) - Table of contents
     - Content area (bd-content) - Main page content
  
  Dependencies:
  - sidebar-left.html: Site navigation and content outline
  - intro.html: Page title, breadcrumbs, and metadata
  - sidebar-right.html: Table of contents and page shortcuts
  
  Bootstrap Classes Used:
  - container-xxl: Extra large responsive container
  - bd-gutter: Custom Bootstrap spacing
  - bd-layout: Custom layout utility class
  - bd-sidebar: Custom sidebar styling
  - bd-main: Main content area
  - bd-toc: Table of contents styling
  - bd-content: Content area styling
  ===================================================================
-->

<!-- ================================================ -->
<!-- MAIN LAYOUT CONTAINER                           -->
<!-- Bootstrap responsive container with custom grid -->
<!-- ================================================ -->
<div class="container-xxl bd-gutter mt-3 my-md-4 bd-layout">

    <!-- ================================ -->
    <!-- LEFT SIDEBAR - Navigation       -->
    <!-- ================================ -->
    <!-- Site navigation, content outline, and offcanvas menu for mobile -->
    <aside class="bd-sidebar">
        <!--
  ===================================================================
  SIDEBAR LEFT - Dynamic Navigation Sidebar
  ===================================================================
  
  File: sidebar-left.html 
  Path: _includes/navigation/sidebar-left.html
  Purpose: Left sidebar navigation with three standardized content modes
  
  Template Logic:
  - Responsive offcanvas sidebar for mobile devices
  - Three navigation modes based on page.sidebar.nav:
    * "auto": Auto-generated folder structure from collection documents
    * "tree": YAML-defined hierarchical navigation from _data/navigation/
    * "categories": Category-based navigation from site categories
  
  Dependencies:
  - sidebar-folders.html: Dynamic folder structure generation (auto mode)
  - sidebar-categories.html: Category-based navigation (categories mode)
  - nav-tree.html: YAML-based hierarchical tree (tree mode)
  - Bootstrap 5 offcanvas component
  
  Navigation Modes:
  1. auto: Scans collection documents to build folder structure
  2. tree: Uses predefined YAML navigation from _data/navigation/*.yml
  3. categories: Groups content by Jekyll categories
  ===================================================================
-->

<!-- ================================ -->
<!-- SIDEBAR NAVIGATION CONTAINER   -->
<!-- ================================ -->
<!-- Responsive offcanvas sidebar - full-width on mobile, fixed on desktop -->
<div class="offcanvas-lg offcanvas-start" tabindex="-1" id="bdSidebar" aria-labelledby="bdSidebarOffcanvasLabel">

  <!-- ========================== -->
  <!-- SIDEBAR HEADER            -->
  <!-- ========================== -->
  <!-- Mobile-only header with close button -->
  <div class="offcanvas-header border-bottom">
    <h5 class="offcanvas-title" id="bdSidebarOffcanvasLabel">Browse docs</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#bdSidebar"></button>
  </div>

  <!-- ========================== -->
  <!-- SIDEBAR CONTENT AREA      -->
  <!-- ========================== -->
  <!-- Scrollable content area with dynamic navigation options -->
  <div class="offcanvas-body overflow-auto">

    <!-- ========================== -->
    <!-- AUTO MODE: Collection Docs -->
    <!-- ========================== -->
    <!-- Auto-generates folder structure from collection documents -->
    
    <nav class="w-100 nav-tree" data-nav-tree>
      <!--
  ===================================================================
  NAV TREE - Flat YAML Navigation Renderer
  ===================================================================
  
  File: nav-tree.html
  Path: _includes/navigation/nav-tree.html
  Purpose: Render hierarchical navigation from YAML data files
  
  Parameters:
  - nav: Name of navigation file in _data/navigation/ (e.g., "docs", "main")
  
  Data Schema (expected in _data/navigation/*.yml):
  - title: string (required) - Display text
  - url: string (optional) - Link URL
  - icon: string (optional) - Bootstrap Icons class (e.g., "bi-folder")
  - expanded: boolean (optional) - Default expanded state (default: false)
  - children: array (optional) - Nested navigation items (max 2 levels)
  
  Note: This implementation supports 2 levels of nesting to avoid Jekyll's
  include depth limit. For deeper nesting, consider a plugin approach.
  
  Dependencies:
  - site.data.navigation[nav]: Navigation YAML data
  - Bootstrap 5 collapse component
  - Bootstrap Icons for visual indicators
  
  Usage:
  include navigation/nav-tree.html nav="docs"
  ===================================================================
-->




<ul class="list-unstyled fw-normal pb-2 small nav-tree-root">
  
    
    
    
    
    
    <li class="mb-1 nav-tree-item" data-depth="0">
      
        <!-- Parent item with children - collapsible -->
        <div class="d-flex align-items-center">
          
            <a href="/quickstart/" 
               class="nav-tree-link flex-grow-1 d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none active">
              <i class="bi-flag me-2"></i>
              <span>Quick Start</span>
            </a>
            <button class="btn btn-sm btn-link nav-tree-toggle p-1"
                    type="button"
                    data-bs-toggle="collapse" 
                    data-bs-target="#nav-quick-start" 
                    aria-expanded="true"
                    aria-controls="nav-quick-start"
                    aria-label="Toggle Quick Start submenu">
              <i class="bi bi-chevron-down"></i>
            </button>
          
        </div>
        
        <!-- Children container (Level 1) -->
        <div class="collapse show" id="nav-quick-start">
          <ul class="list-unstyled fw-normal ps-3 nav-tree-children">
            
              
              
              
              
              
              <li class="mb-1 nav-tree-item" data-depth="1">
                
                  <!-- Level 1 leaf item -->
                  
                    <a href="/quickstart/machine-setup/" 
                       class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none active">
                      <i class="bi-laptop me-2"></i>
                      <span>1. Machine Setup</span>
                    </a>
                  
                
              </li>
            
              
              
              
              
              
              <li class="mb-1 nav-tree-item" data-depth="1">
                
                  <!-- Level 1 leaf item -->
                  
                    <a href="/quickstart/jekyll-setup/" 
                       class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none active">
                      <i class="bi-code-square me-2"></i>
                      <span>2. Jekyll Setup</span>
                    </a>
                  
                
              </li>
            
              
              
              
              
              
              <li class="mb-1 nav-tree-item" data-depth="1">
                
                  <!-- Level 1 leaf item -->
                  
                    <a href="/quickstart/github-setup/" 
                       class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none active">
                      <i class="bi-github me-2"></i>
                      <span>3. GitHub Setup</span>
                    </a>
                  
                
              </li>
            
              
              
              
              
              
              <li class="mb-1 nav-tree-item" data-depth="1">
                
                  <!-- Level 1 leaf item -->
                  
                    <a href="/quickstart/personalization/" 
                       class="nav-tree-link d-inline-flex align-items-center rounded py-1 px-2 text-decoration-none active">
                      <i class="bi-palette me-2"></i>
                      <span>4. Personalization</span>
                    </a>
                  
                
              </li>
            
          </ul>
        </div>
      
    </li>
  
</ul>


    </nav>
    
    
  </div>
</div>

    </aside>
    
    <!-- ================================ -->
    <!-- MAIN CONTENT AREA               -->
    <!-- ================================ -->
    <!-- Primary content section with scroll spy for table of contents navigation -->
    <main class="bd-main order-1" data-bs-spy="scroll" data-bs-target="#TableOfContents" data-bs-offset="100" data-bs-smooth-scroll="true">

        <!-- Page introduction: title, breadcrumbs, metadata -->
        <!--
  file: _includes/intro.html
  description: Enhanced intro section with improved share functionality and better button alignment
  path: _includes/intro.html
  features:
    - Responsive share dropdown with multiple social platforms
    - Properly aligned action buttons at bottom right
    - Improved accessibility with icons and labels
    - Clean button grouping with consistent spacing
--> 


<!-- Intro Section -->








<div class="bd-intro pt-5 ps-lg-2 position-relative" style="
  background: linear-gradient(rgba(0, 0, 0, 0.5), rgba(0, 0, 0, 0.5)), url('/assets/images/previews/zer0-mistakes-quick-start-guide.png') no-repeat center center / cover;
  color: #fff;">

  <br>
  <h1>Zer0-Mistakes Quick Start Guide</h1>
  <p>By Zer0-Mistakes Development Team</p>
  <p>Complete setup guide for the Zer0-Mistakes Jekyll theme featuring Docker-first development, AI-powered installation, and cross-platform compatibility</p>
  <p>Estimated reading time: 4 minutes</p>
  <!-- Action Buttons Group -->
  <div class="position-absolute bottom-0 end-0 m-3 d-flex gap-2">
    <!-- Share Button -->
    <div class="dropdown">
      <button class="btn btn-info dropdown-toggle" type="button" id="shareDropdownBottom" data-bs-toggle="dropdown" aria-expanded="false">
        <i class="bi bi-share"></i>
        <span class="d-none d-sm-inline ms-1">Share</span>
      </button>
      <ul class="dropdown-menu dropdown-menu-end" aria-labelledby="shareDropdownBottom">
        <li>
          <a class="dropdown-item" href="https://reddit.com/submit?url=https%3A%2F%2Fzer0-mistakes.com%2Fquickstart%2F&amp;title=Zer0-Mistakes+Quick+Start+Guide" target="_blank">
            <i class="bi bi-reddit me-2"></i>Share on Reddit
          </a>
        </li>
        <li>
          <a class="dropdown-item" href="https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fzer0-mistakes.com%2Fquickstart%2F" target="_blank">
            <i class="bi bi-linkedin me-2"></i>Share on LinkedIn
          </a>
        </li>
        <li>
          <a class="dropdown-item" href="https://twitter.com/intent/tweet?url=https%3A%2F%2Fzer0-mistakes.com%2Fquickstart%2F&text=Zer0-Mistakes+Quick+Start+Guide" target="_blank">
            <i class="bi bi-twitter me-2"></i>Share on Twitter
          </a>
        </li>
        <li><hr class="dropdown-divider"></li>
        <li>
          <button class="dropdown-item" onclick='navigator.clipboard.writeText("https://zer0-mistakes.com/quickstart/"); alert("Link copied to clipboard!");'>
            <i class="bi bi-clipboard me-2"></i>Copy Link
          </button>
        </li>
      </ul>
    </div>

    <!-- Edit on Github Button -->
    <a href="https://github.com/bamr87/zer0-mistakes/blob/master/pages/_quickstart/index.md" class="btn btn-dark">
      <i class="bi bi-github"></i>
      <span class="d-none d-sm-inline ms-1">Edit on GitHub</span>
    </a>
  </div>
</div>

        <!-- =============================== -->
        <!-- RIGHT SIDEBAR - Table of Contents -->
        <!-- =============================== -->
        <!-- Page outline, shortcuts, and related links (hidden on mobile) -->
        <div class="bd-toc text-body-secondary">
            <!-- 
  file: sidebar-right.html 
  path: _includes/sidebar-right.html
  includes: nav_list.html, content/toc.html
-->

<!-- TOC button in mobile view - Floating Action Button pattern -->
<!-- Positioned above back-to-top button to prevent overlap -->
<div class="d-lg-none position-fixed bd-toc-fab" style="bottom: 90px; right: 20px; z-index: 1030;">
  <button class="btn btn-primary rounded-circle shadow-lg bd-toc-toggle" 
          type="button" 
          data-bs-toggle="offcanvas" 
          data-bs-target="#tocContents" 
          aria-controls="tocContents"
          aria-label="Toggle Table of Contents"
          style="width: 56px; height: 56px;">
    <i class="bi bi-list-ul fs-5"></i>
  </button>
</div>

<!-- Right sidebar container -->
<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="tocContents" aria-labelledby="tocLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="tocLabel">Table of Contents</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close" data-bs-target="#tocContents"></button>
  </div>
  <div class="offcanvas-body">
    <!-- Table of contents -->
    <nav id="TableOfContents" role="navigation" aria-label="Table of Contents">
      <!-- TOC title -->
      <div class="mb-3">
        <strong class="d-flex align-items-center">
          <i class="bi bi-file-text me-2"></i>
          On this page
        </strong>
      </div>

    <!-- TOC list -->

    <!-- TOC list -->
      <ul class="list-group-flush"><li class="list-group-item"><a href="#-quick-start-guide" class="">🚀 Quick Start Guide</a><ul><li class="list-group-item"><a href="#fastest-start-1-command" class="">⚡ Fastest Start (1 Command)</a></li><li class="list-group-item"><a href="#-what-you-get" class="">🎯 What You Get</a></li><li class="list-group-item"><a href="#-installation-options" class="">🔄 Installation Options</a><ul><li class="list-group-item"><a href="#option-a-ai-install-wizard-recommended" class="">Option A: AI Install Wizard (Recommended)</a></li><li class="list-group-item"><a href="#option-b-github-template-repository" class="">Option B: GitHub Template Repository</a></li><li class="list-group-item"><a href="#option-c-github-codespaces-zero-install" class="">Option C: GitHub Codespaces (Zero Install)</a></li><li class="list-group-item"><a href="#option-d-forkclone-theme-development" class="">Option D: Fork/Clone (Theme Development)</a></li><li class="list-group-item"><a href="#option-e-remote-theme-github-pages" class="">Option E: Remote Theme (GitHub Pages)</a></li><li class="list-group-item"><a href="#option-f-ruby-gem" class="">Option F: Ruby Gem</a></li></ul></li><li class="list-group-item"><a href="#-comprehensive-setup-guides" class="">📚 Comprehensive Setup Guides</a><ul><li class="list-group-item"><a href="#essential-setup" class="">🏗️ Essential Setup</a></li><li class="list-group-item"><a href="#advanced-configuration" class="">🚀 Advanced Configuration</a></li><li class="list-group-item"><a href="#-development-tools" class="">🔧 Development Tools</a></li></ul></li><li class="list-group-item"><a href="#-development-workflows" class="">🎯 Development Workflows</a><ul><li class="list-group-item"><a href="#local-development" class="">Local Development</a></li><li class="list-group-item"><a href="#theme-customization" class="">Theme Customization</a></li></ul></li><li class="list-group-item"><a href="#-quick-troubleshooting" class="">🔧 Quick Troubleshooting</a><ul><li class="list-group-item"><a href="#installation-issues" class="">Installation Issues</a></li><li class="list-group-item"><a href="#validation-commands" class="">Validation Commands</a></li></ul></li><li class="list-group-item"><a href="#-need-help" class="">🆘 Need Help?</a></li><li class="list-group-item"><a href="#-next-steps" class="">🚀 Next Steps</a></li></ul></li></ul>

    </nav>
  </div>
</div>
   


        </div>
        
        <!-- =============================== -->
        <!-- MAIN CONTENT BODY              -->
        <!-- =============================== -->
        <!-- Where the actual page content is rendered -->
        <div class="bd-content ps-lg-2">
            <h1 id="-quick-start-guide">🚀 Quick Start Guide</h1>

<p>Get your <strong>zer0-mistakes</strong> Jekyll site running in under 5 minutes with our intelligent installation system.</p>

<p>For the full install + personalization workflow (all methods, config layering, and troubleshooting), use the canonical repo guide:</p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">https://github.com/bamr87/zer0-mistakes/blob/main/QUICKSTART.md</code></li>
</ul>

<h2 id="fastest-start-1-command">⚡ Fastest Start (1 Command)</h2>

<p><strong>For immediate results:</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Create and setup new site</span>
<span class="nb">mkdir </span>my-site <span class="o">&amp;&amp;</span> <span class="nb">cd </span>my-site
curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash <span class="o">&amp;&amp;</span> docker-compose up
</code></pre></div></div>

<p><strong>That’s it!</strong> Your site will be running at <code class="language-plaintext highlighter-rouge">http://localhost:4000</code></p>

<h2 id="-what-you-get">🎯 What You Get</h2>

<ul>
  <li><strong>🤖 AI-Powered Setup</strong> - Intelligent error detection and automatic fixes</li>
  <li><strong>🐳 Docker Environment</strong> - Consistent development across all platforms</li>
  <li><strong>🎨 Bootstrap 5.3</strong> - Modern responsive design with dark mode</li>
  <li><strong>📱 Mobile-First</strong> - Optimized for all devices and screen sizes</li>
  <li><strong>⚡ Live Reload</strong> - Changes appear instantly during development</li>
  <li><strong>🛡️ Error Recovery</strong> - Self-healing installation with detailed diagnostics</li>
</ul>

<h2 id="-installation-options">🔄 Installation Options</h2>

<table>
  <thead>
    <tr>
      <th>Path</th>
      <th>Method</th>
      <th>Best For</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>A</strong></td>
      <td>AI Install Wizard</td>
      <td>Creating a new site (recommended)</td>
    </tr>
    <tr>
      <td><strong>B</strong></td>
      <td>GitHub Template</td>
      <td>One-click copy of the entire repo</td>
    </tr>
    <tr>
      <td><strong>C</strong></td>
      <td>GitHub Codespaces</td>
      <td>Zero-install cloud development</td>
    </tr>
    <tr>
      <td><strong>D</strong></td>
      <td>Fork/Clone</td>
      <td>Theme development &amp; customization</td>
    </tr>
    <tr>
      <td><strong>E</strong></td>
      <td>Remote Theme</td>
      <td>GitHub Pages without copying files</td>
    </tr>
    <tr>
      <td><strong>F</strong></td>
      <td>Ruby Gem</td>
      <td>Traditional Jekyll workflow</td>
    </tr>
  </tbody>
</table>

<h3 id="option-a-ai-install-wizard-recommended">Option A: AI Install Wizard (Recommended)</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">mkdir </span>my-site <span class="o">&amp;&amp;</span> <span class="nb">cd </span>my-site
curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
docker-compose up
</code></pre></div></div>

<h3 id="option-b-github-template-repository">Option B: GitHub Template Repository</h3>

<ol>
  <li>Go to <a href="https://github.com/bamr87/zer0-mistakes">github.com/bamr87/zer0-mistakes</a></li>
  <li>Click <strong>“Use this template”</strong> → <strong>“Create a new repository”</strong></li>
  <li>Clone your new repo and run <code class="language-plaintext highlighter-rouge">docker-compose up</code></li>
</ol>

<p>Or via CLI:</p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gh repo create my-site <span class="nt">--template</span> bamr87/zer0-mistakes <span class="nt">--clone</span>
<span class="nb">cd </span>my-site <span class="o">&amp;&amp;</span> docker-compose up
</code></pre></div></div>

<h3 id="option-c-github-codespaces-zero-install">Option C: GitHub Codespaces (Zero Install)</h3>

<p><a href="https://codespaces.new/bamr87/zer0-mistakes"><img src="https://github.com/codespaces/badge.svg" alt="Open in GitHub Codespaces" /></a></p>

<p>Or from the repo page: <strong>Code</strong> → <strong>Codespaces</strong> → <strong>Create codespace on main</strong></p>

<h3 id="option-d-forkclone-theme-development">Option D: Fork/Clone (Theme Development)</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gh repo fork bamr87/zer0-mistakes <span class="nt">--clone</span>
<span class="nb">cd </span>zer0-mistakes
docker-compose up
</code></pre></div></div>

<h3 id="option-e-remote-theme-github-pages">Option E: Remote Theme (GitHub Pages)</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gh repo create my-site <span class="nt">--public</span> <span class="nt">--clone</span>
<span class="nb">cd </span>my-site
<span class="nb">echo</span> <span class="s2">"remote_theme: bamr87/zer0-mistakes"</span> <span class="o">&gt;</span> _config.yml
<span class="c"># Enable GitHub Pages in repository Settings</span>
</code></pre></div></div>

<h3 id="option-f-ruby-gem">Option F: Ruby Gem</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">echo</span> <span class="s1">'gem "jekyll-theme-zer0"'</span> <span class="o">&gt;&gt;</span> Gemfile
bundle <span class="nb">install</span>
<span class="c"># Set theme: jekyll-theme-zer0 in _config.yml</span>
</code></pre></div></div>

<p>For the complete setup guide with all options and troubleshooting, see <a href="https://github.com/bamr87/zer0-mistakes/blob/main/QUICKSTART.md">QUICKSTART.md</a>.</p>

<h2 id="-comprehensive-setup-guides">📚 Comprehensive Setup Guides</h2>

<h3 id="essential-setup">🏗️ Essential Setup</h3>

<table>
  <thead>
    <tr>
      <th>Guide</th>
      <th>Purpose</th>
      <th>Time</th>
      <th>Difficulty</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong><a href="/quickstart/machine-setup/">Machine Setup</a></strong></td>
      <td>Install Docker, Git, and platform tools</td>
      <td>10 min</td>
      <td>Beginner</td>
    </tr>
    <tr>
      <td><strong><a href="/quickstart/jekyll-setup/">Jekyll Setup</a></strong></td>
      <td>Configure theme and development environment</td>
      <td>5 min</td>
      <td>Beginner</td>
    </tr>
    <tr>
      <td><strong><a href="/quickstart/github-setup/">GitHub Setup</a></strong></td>
      <td>Version control and deployment</td>
      <td>10 min</td>
      <td>Intermediate</td>
    </tr>
  </tbody>
</table>

<h3 id="advanced-configuration">🚀 Advanced Configuration</h3>

<table>
  <thead>
    <tr>
      <th>Guide</th>
      <th>Purpose</th>
      <th>Time</th>
      <th>Difficulty</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Bootstrap Customization</strong></td>
      <td>Modify themes and responsive design</td>
      <td>15 min</td>
      <td>Intermediate</td>
    </tr>
    <tr>
      <td><strong>Performance Optimization</strong></td>
      <td>Speed up loading and Core Web Vitals</td>
      <td>20 min</td>
      <td>Advanced</td>
    </tr>
    <tr>
      <td><strong>Custom Hosting</strong></td>
      <td>Deploy to Netlify, Vercel, or custom servers</td>
      <td>15 min</td>
      <td>Intermediate</td>
    </tr>
  </tbody>
</table>

<h3 id="-development-tools">🔧 Development Tools</h3>

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Purpose</th>
      <th>Setup Time</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>VS Code Extensions</strong></td>
      <td>Enhanced Jekyll development</td>
      <td>5 min</td>
    </tr>
    <tr>
      <td><strong>GitHub CLI</strong></td>
      <td>Repository management</td>
      <td>5 min</td>
    </tr>
    <tr>
      <td><strong>Docker Desktop</strong></td>
      <td>Containerized development</td>
      <td>10 min</td>
    </tr>
  </tbody>
</table>

<h2 id="-development-workflows">🎯 Development Workflows</h2>

<h3 id="local-development">Local Development</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Start development environment</span>
docker-compose up

<span class="c"># Access your site</span>
open http://localhost:4000
</code></pre></div></div>

<h3 id="theme-customization">Theme Customization</h3>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Customize layouts and includes</span>
edit _layouts/default.html
edit _includes/header.html

<span class="c"># Modify styles</span>
edit assets/css/custom.css
</code></pre></div></div>

<h2 id="-quick-troubleshooting">🔧 Quick Troubleshooting</h2>

<h3 id="installation-issues">Installation Issues</h3>

<p><strong>Problem: Installation fails</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Check Docker is running</span>
docker <span class="nt">--version</span>

<span class="c"># Try minimal installation first</span>
curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash <span class="nt">-s</span> <span class="nt">--</span> <span class="nt">--minimal</span>
</code></pre></div></div>

<p><strong>Problem: Port 4000 in use</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Check what's using the port</span>
lsof <span class="nt">-i</span> :4000

<span class="c"># Use different port</span>
docker-compose run <span class="nt">-p</span> 4001:4000 jekyll
</code></pre></div></div>

<p><strong>Problem: Docker platform warnings</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># This is normal on Apple Silicon - the site will still work</span>
<span class="c"># The docker-compose.yml already includes platform: linux/amd64</span>
</code></pre></div></div>

<h3 id="validation-commands">Validation Commands</h3>

<p><strong>Test your installation:</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># New site install (generated project):</span>
<span class="c"># - Confirm files exist and Docker config parses</span>
<span class="nb">ls</span> <span class="nt">-la</span>
docker-compose config

<span class="c"># Theme repo (this repository):</span>
./test/test_runner.sh
</code></pre></div></div>

<h2 id="-need-help">🆘 Need Help?</h2>

<table>
  <thead>
    <tr>
      <th>Resource</th>
      <th>Purpose</th>
      <th>Response Time</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong><a href="https://github.com/bamr87/zer0-mistakes/issues">GitHub Issues</a></strong></td>
      <td>Bug reports and technical support</td>
      <td>24-48 hours</td>
    </tr>
    <tr>
      <td><strong><a href="https://github.com/bamr87/zer0-mistakes/discussions">Discussions</a></strong></td>
      <td>Community Q&amp;A and feature requests</td>
      <td>Community-driven</td>
    </tr>
    <tr>
      <td><strong><a href="https://bamr87.github.io/zer0-mistakes/">Documentation</a></strong></td>
      <td>Comprehensive guides and tutorials</td>
      <td>Immediate</td>
    </tr>
    <tr>
      <td><strong>AI Diagnostics</strong></td>
      <td>Built-in automated troubleshooting</td>
      <td>Immediate</td>
    </tr>
  </tbody>
</table>

<h2 id="-next-steps">🚀 Next Steps</h2>

<p><strong>🎯 Immediate Actions:</strong></p>

<ol>
  <li>Run the <a href="#fastest-start-1-command">one-command installation</a></li>
  <li>Verify with the <a href="#validation-commands">validation commands</a></li>
  <li>Start customizing your site content</li>
</ol>

<p><strong>📚 Learn More:</strong></p>

<ol>
  <li>Follow the <a href="#essential-setup">essential setup guides</a></li>
  <li>Explore <a href="#advanced-configuration">advanced configuration options</a></li>
  <li>Join our <a href="https://github.com/bamr87/zer0-mistakes/discussions">community discussions</a></li>
</ol>

<p><strong>🚀 Deploy:</strong></p>

<ol>
  <li>Push to GitHub for automatic Pages deployment</li>
  <li>Configure custom domain if needed</li>
  <li>Monitor performance with built-in tools</li>
</ol>

<hr />

<p><strong>Ready to build something amazing?</strong> Start with the <a href="#fastest-start-1-command">fastest installation</a> above!</p>

        </div>
    </main>
</div></main>
  </div>
</div>

🔧 Advanced Configuration

Environment Variables

Use Docker Compose environment variables:

# docker-compose.yml
services:
  jekyll:
    environment:
      - JEKYLL_ENV=development
      - PAGES_REPO_NWO=username/repository

Custom Plugins

Add plugins in _plugins/ directory:

# _plugins/custom_tag.rb
module Jekyll
  class CustomTag < Liquid::Tag
    def render(context)
      "Custom content here"
    end
  end
end

Liquid::Template.register_tag('custom', Jekyll::CustomTag)

Performance Optimization

# _config.yml performance settings
sass:
  style: compressed

# Exclude unnecessary files
exclude:
  - node_modules/
  - vendor/
  - .bundle/
  - .sass-cache/

# Enable incremental builds
incremental: true

🚀 Deployment

GitHub Pages (Automatic)

  1. Push changes to main branch
  2. GitHub Actions builds automatically
  3. Site deploys to https://username.github.io

Manual Build

# Build for production
docker-compose exec jekyll jekyll build --config _config.yml

# Output in _site/ directory
ls -la _site/

🐛 Troubleshooting

Common Issues

Site Not Loading

# Check if container is running
docker-compose ps

# View detailed logs
docker-compose logs jekyll

# Restart with fresh build
docker-compose down && docker-compose up --build

Permission Issues (macOS/Linux)

# Fix file permissions
sudo chown -R $USER:$USER .

Port Already in Use

# Find process using port 4000
lsof -i :4000

# Kill process
kill -9 $(lsof -t -i:4000)

Container Build Failures

# Clean Docker system
docker system prune -f

# Rebuild without cache
docker-compose build --no-cache

Getting Help

  1. Check Logs: Always start with docker-compose logs
  2. Jekyll Doctor: Run docker-compose exec jekyll jekyll doctor
  3. GitHub Issues: Report problems at zer0-mistakes/issues
  4. Discord Community: Join our development community

📚 Next Steps

After setting up Jekyll development:

  1. Explore the Theme: Review existing layouts and includes
  2. Create Content: Write your first blog post
  3. Customize Design: Modify Bootstrap components
  4. Deploy: Push to GitHub for automatic deployment
  5. Advanced Features: Explore collections and custom plugins

🎯 Quick Reference

Essential Commands

# Start development
docker-compose up

# Stop development
docker-compose down

# View logs
docker-compose logs -f

# Shell access
docker-compose exec jekyll bash

# Build for production
docker-compose exec jekyll jekyll build

File Structure

zer0-mistakes/
├── _config.yml          # Production config
├── _config_dev.yml       # Development config
├── docker-compose.yml    # Container setup
├── pages/
│   ├── _posts/          # Blog posts
│   └── _quickstart/     # Documentation
├── _layouts/            # Page templates
├── _includes/           # Reusable components
├── assets/
│   ├── css/            # Custom styles
│   └── js/             # Custom scripts
└── _site/              # Generated site (ignored)

🚀 Next Steps

Now that your Jekyll development environment is running:

  1. Set up GitHub for version control and deployment
  2. Personalize your site with custom branding and configuration
  3. Create your first post using the frontmatter template above
Previous: Machine Setup Next: GitHub Setup

Pass the --livereload option to serve to automatically refresh the page with each change you make to the source files: bundle exec jekyll serve --livereload

If you encounter any errors during this process, check that you have installed all the prerequisites in Requirements. If you still have issues, see Troubleshooting.

Installation varies based on your operating system. See our guides for OS-specific instructions.

We value your privacy

This website uses cookies and similar technologies to enhance your browsing experience, analyze traffic, and provide personalized content. Learn more in our Privacy Policy.