Jekyll Setup

By Amr

Complete Docker-first Jekyll setup guide for Zer0-Mistakes theme development

Estimated reading time: 25 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:

  1. Docker Desktop (installed via Machine Setup)
  2. Git & GitHub CLI (configured via GitHub Setup)
  3. VS Code with recommended extensions
  4. Zer0-Mistakes repository forked and cloned

πŸ—οΈ 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:

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: "Social media preview text"
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/sidebar-left.html
  Purpose: Left sidebar navigation with multiple content modes including
           dynamic page listing, category browsing, and manual navigation
  
  Template Logic:
  - Responsive offcanvas sidebar for mobile devices
  - Three navigation modes based on page.sidebar.nav:
    * "dynamic": Auto-generated folder structure from pages
    * "searchCats": Category-based navigation from site categories
    * Manual: Predefined navigation from _data files
  
  Dependencies:
  - sidebar-folders.html: Dynamic folder structure generation
  - sidebar-categories.html: Category-based navigation
  - nav_list.html: Manual navigation list rendering
  - Bootstrap 5 offcanvas component
  
  Navigation Modes:
  1. Dynamic: Scans site.pages for index.md files to build folder structure
  2. Categories: Groups content by Jekyll categories
  3. Manual: Uses predefined navigation from _data/navigation.yml
  ===================================================================
-->

<!-- ================================ -->
<!-- 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">

    <!-- ========================== -->
    <!-- DYNAMIC PAGE LISTING      -->
    <!-- ========================== -->
    <!-- Auto-generates folder structure from pages containing index.md -->
    
    <nav class="w-100">
      <!--
  file: nav_list.html
  path: /_includes/nav_list.html
  includes:
-->

<!-- Navigation List -->



  <!-- Navigation Title -->
  
    
  


  
  <ul class="list-unstyled fw-normal pb-2 small">
  <!-- Accordion Nav List -->
  
      <!-- Nav Title Only Link -->
      

      
        <li class="mb-1">
          <strong class="d-flex w-100 align-items-center fw-semibold collapsed"
          data-bs-toggle="collapse" 
          data-bs-target="#Quick Start-collapse" 
          aria-expanded="true" 
          aria-current="true">
            Quick Start
          </strong>
          <!-- <button class="btn d-inline-flex align-items-center rounded collapsed" 
                  data-bs-toggle="collapse" 
                  data-bs-target="#Quick Start-collapse" 
                  aria-expanded="true" 
                  aria-current="true">
            Quick Start
          </button> -->
          <div class="collapse show" id="Quick Start-collapse" style="">
            <ul class="list-unstyled fw-normal pb-1 small">
              
                <li>
                  <a href="/quickstart/machine-setup/"
                    
                      >Machine Setup
                  </a>
                </li>
              
                <li>
                  <a href="/quickstart/jekyll-setup/"
                    
                      >Jekyll Setup
                  </a>
                </li>
              
                <li>
                  <a href="/quickstart/github-setup/"
                    
                      >GitHub Setup
                  </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-spy="scroll" data-bs-target="toc-content" data-offset="0">

        <!-- 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/Get started with Zer0-Mistakes Jekyll theme in minutes') 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  -->
<div class="d-flex justify-content-end position-fixed top-50 end-0 translate-middle-y me-3">

  <button class="btn bg-opacity-2 bd-toc-toggle d-lg-none border z-2" type="button" data-bs-toggle="offcanvas" data-bs-target="#tocContents" aria-controls="tocContents">
    <i class="bi bi-list-ul"></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">
      <!-- TOC tile -->
      <div>
        <strong>
          <i class="fas fa-file-alt"></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="#-step-by-step-installation" class="">πŸ”„ Step-by-Step Installation</a><ul><li class="list-group-item"><a href="#option-1-automated-setup-recommended" class="">Option 1: Automated Setup (Recommended)</a></li><li class="list-group-item"><a href="#option-2-github-pages-setup" class="">Option 2: GitHub Pages Setup</a></li><li class="list-group-item"><a href="#option-3-local-development" class="">Option 3: Local Development</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="#content-creation" class="">Content Creation</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 id="main-content" 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>

<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="-step-by-step-installation">πŸ”„ Step-by-Step Installation</h2>

<h3 id="option-1-automated-setup-recommended">Option 1: Automated Setup (Recommended)</h3>

<p><strong>For new sites:</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 1. Create project directory</span>
<span class="nb">mkdir </span>my-awesome-site <span class="o">&amp;&amp;</span> <span class="nb">cd </span>my-awesome-site

<span class="c"># 2. Run intelligent installer</span>
curl <span class="nt">-fsSL</span> https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash

<span class="c"># 3. Start development server</span>
docker-compose up

<span class="c"># 4. Open in browser</span>
open http://localhost:4000
</code></pre></div></div>

<h3 id="option-2-github-pages-setup">Option 2: GitHub Pages Setup</h3>

<p><strong>For GitHub Pages hosting:</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 1. Create repository on GitHub</span>
gh repo create my-site <span class="nt">--public</span>

<span class="c"># 2. Clone and setup</span>
git clone https://github.com/USERNAME/my-site.git
<span class="nb">cd </span>my-site

<span class="c"># 3. Add remote theme to _config.yml</span>
<span class="nb">echo</span> <span class="s2">"remote_theme: bamr87/zer0-mistakes"</span> <span class="o">&gt;</span> _config.yml

<span class="c"># 4. Enable GitHub Pages in repository settings</span>
</code></pre></div></div>

<h3 id="option-3-local-development">Option 3: Local Development</h3>

<p><strong>For theme development:</strong></p>

<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># 1. Fork and clone</span>
gh repo fork bamr87/zer0-mistakes <span class="nt">--clone</span>
<span class="nb">cd </span>zer0-mistakes

<span class="c"># 2. Start development</span>
docker-compose up
</code></pre></div></div>

<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="content-creation">Content Creation</h3>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># Create new post</span>
bundle <span class="nb">exec </span>jekyll post <span class="s2">"My New Post"</span>

<span class="c"># Create new page</span>
bundle <span class="nb">exec </span>jekyll page <span class="s2">"About"</span>
</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"># Verify files were installed</span>
<span class="nb">ls</span> <span class="nt">-la</span> _config.yml docker-compose.yml INSTALLATION.md

<span class="c"># Test Docker configuration</span>
docker-compose config

<span class="c"># Run automated tests</span>
./test/test_installation_complete.sh <span class="nt">--verbose</span>
</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)

Ready to start developing? Run docker-compose up and visit http://localhost:4000 to see your site in action! πŸŽ‰

Jekyll is a static site generator. It takes text written in your favorite markup language and uses layouts to create a static website. You can tweak the site’s look and feel, URLs, the data displayed on the page, and more.

Prerequisites

Jekyll requires the following:

  • Ruby version ** or higher
  • RubyGems
  • GCC and Make

If you want to use Github Pages, here are the dependencies

Instructions

  1. Create a new Jekyll site at ./mysite.
cd ~/github/
jekyll new mysite
  1. Change into your new directory. 
    cd mysite
  2. Build the site and make it available on a local server. 
    bundle exec jekyll serve
  3. Browse to http://localhost:4000

If you are using Ruby version 3.0.0 or higher, step 5 may fail. You may fix it by adding webrick to your dependencies: bundle add webrick

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.