Jekyll

By Amr

Jekyll basics and Zer0-Mistakes development workflow (Docker-first).

Estimated reading time: 2 minutes

• Share on Reddit
• Share on LinkedIn
• Share on Twitter

• ---

• Article Review Review article structure, metadata, and SEO
• Code Implementation Implement a feature with production-ready code
• Code Refactoring Refactor code for quality, readability, and performance
• Debugging Diagnose and fix issues in the code
• Documentation Generate or improve technical documentation
• Requirements Analysis Convert ideas into structured technical requirements
• System Design Design a scalable system architecture
• Test Generation Generate comprehensive tests for code
• Prompt Engineering Craft an effective AI prompt for this task

Edit on GitHub

Table of Contents

Jekyll

Jekyll is the static site generator that powers Zer0-Mistakes. This section covers everything you need to work with Jekyll effectively.

Quick Start

Prerequisites

• Complete the Installation Guide
• Have Docker Desktop running (or Ruby + Bundler installed)

Run Locally

# With Docker (recommended)
docker-compose up

# Without Docker
bundle exec jekyll serve --config "_config.yml,_config_dev.yml"

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

Key Concepts

Directory Structure

Directory	Purpose
_layouts/	Page templates (HTML with Liquid)
_includes/	Reusable components
_data/	Site data files (YAML, JSON)
_sass/	Stylesheet partials
pages/	Content collections
assets/	Static files (CSS, JS, images)

Configuration Files

File	Purpose
_config.yml	Production configuration
_config_dev.yml	Development overrides
Gemfile	Ruby dependencies

Content Collections

Zer0-Mistakes organizes content in collections under pages/:

• _posts/ - Blog posts
• _docs/ - Documentation
• _quests/ - Tutorials and learning paths
• _about/ - About pages

Essential Commands

# Build the site
docker-compose exec jekyll jekyll build

# Build with verbose output
docker-compose exec jekyll jekyll build --verbose

# Check for configuration issues
docker-compose exec jekyll jekyll doctor

# Clean build artifacts
docker-compose exec jekyll jekyll clean

Documentation Topics

Configuration & Setup

• Jekyll Configuration — Site settings and options
• Front Matter — Page metadata and options
• Code Highlighting — Syntax highlighting
• Pagination — Post navigation

Features

See the Features section for:

• Mermaid Diagrams — Flowcharts and diagrams
• MathJax Math — Mathematical notation
• Giscus Comments — GitHub Discussions comments
• PostHog Analytics — Privacy-first analytics

Deployment

See the Deployment section for:

• GitHub Pages — Free hosting with GitHub
• Netlify — Advanced hosting features
• Custom Domain — Use your own domain

Resources

• Official Jekyll Documentation
• Jekyll GitHub Repository
• Liquid Template Language

Related

• Ruby & Bundler — Ruby dependency management
• Liquid Templating — Template language reference
• Docker Development — Container-based workflow