Jekyll
By Amr
Jekyll basics and Zer0-Mistakes development workflow (Docker-first).
Estimated reading time: 2 minutes
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
Related
- Ruby & Bundler — Ruby dependency management
- Liquid Templating — Template language reference
- Docker Development — Container-based workflow