Skip to content

Install a modern Ruby with Homebrew (the system Ruby is too old)

Greetings, brave adventurer! Welcome to Jekyll Fundamentals - your first true step into the realm of the web. In the previous tier you learned to wield the terminal and the version-control scrolls. Now you will forge something the whole world can visit: a website. And you will build it the wise way - as a fast, secure static site that needs no database and no fragile server to defend.

Whether you have never written a line of HTML or you are an old hand looking to ship sites without the weight of a content-management beast, this adventure will teach you the "how" and, more importantly, the "why" behind the static web.

📖 The Legend Behind This Quest

In the early days, every web page was conjured fresh on each visit - the server would wake a database, run code, assemble the page, and only then send it. That let every page be personalized per visitor, but it was slow, costly, and full of trap doors for attackers. Then a band of builders realized a simple truth: most pages do not change between visitors. Why rebuild the castle every time someone knocks? Jekyll was born from this insight - generate every page once, ahead of time, and serve plain files. The result is a site that loads instantly, costs nearly nothing to host, and has almost no attack surface.

Jekyll, written in Ruby, powers GitHub Pages and countless documentation sites, blogs, and portfolios across the kingdom. Master it, and you hold the foundation stone of the entire Web Fundamentals tier.

🎯 Quest Objectives

By the time you complete this journey, you will have mastered:

Primary Objectives (Required for Quest Completion)

  • What a Static Site Generator Is - Explain how Jekyll turns source files into a finished website
  • The Jekyll Directory Structure - Recognize every special folder and what it does
  • Collections & Content - Add posts, pages, and a custom collection
  • The Build & Serve Loop - Run jekyll build and jekyll serve and read the output

Secondary Objectives (Bonus Achievements)

  • Bundler & Gemfile - Manage Jekyll and plugins reproducibly
  • Front Matter Basics - Add metadata to a page that controls how it renders
  • Drafts & Live Reload - Use --drafts and --livereload to speed up authoring

Mastery Indicators

You'll know you've truly mastered this quest when you can: - [ ] Explain to a friend why a static site is faster and safer than a dynamic one - [ ] Scaffold a new Jekyll site and serve it without looking up the commands - [ ] Point to the _site folder and say exactly what lives there and why

🗺️ Quest Prerequisites

📋 Knowledge Requirements

  • Basic command line navigation (cd, ls, mkdir)
  • Comfort creating and editing plain text files
  • Recommended: completion of Git Basics

🛠️ System Requirements

  • Modern operating system (Windows 10+, macOS 10.14+, or Linux)
  • Ruby 3.x installed (we install it below)
  • A text editor or IDE (VS Code recommended)
  • Internet connection for downloading gems

🧠 Skill Level Indicators

This 🟢 Easy quest expects: - [ ] Beginner-friendly - no prior Jekyll or Ruby experience required - [ ] Comfortable running commands you copy into a terminal - [ ] Ready for 75-90 minutes of focused learning

🌍 Choose Your Adventure Platform

Jekyll needs Ruby and a couple of build tools. Pick the path that matches your machine.

🍎 macOS Kingdom Path

Click to expand macOS instructions 
# Install a modern Ruby with Homebrew (the system Ruby is too old)
brew install ruby

# Add the Homebrew Ruby to your PATH (zsh)
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Install Jekyll and Bundler
gem install jekyll bundler

# Verify
ruby --version
jekyll --version

macOS-Specific Notes: - On Apple Silicon Homebrew lives in /opt/homebrew; on Intel Macs it is /usr/local. - Never sudo gem install - it pollutes the system Ruby.

🪟 Windows Empire Path

Click to expand Windows instructions 
# Install RubyInstaller with DevKit via winget
winget install RubyInstallerTeam.RubyWithDevKit.3.2

# Close and reopen the terminal, then install the toolchain when prompted
ridk install

# Install Jekyll and Bundler
gem install jekyll bundler

# Verify
ruby --version
jekyll --version

Windows-Specific Notes: - Choose option 3 during ridk install to build native gems. - WSL2 with Ubuntu is an excellent alternative - follow the Linux path inside it.

🐧 Linux Territory Path

Click to expand Linux instructions 
# Debian / Ubuntu
sudo apt update && sudo apt install -y ruby-full build-essential zlib1g-dev

# Fedora / RHEL
# sudo dnf install -y ruby ruby-devel @development-tools

# Install gems to your home directory (no sudo)
echo 'export GEM_HOME="$HOME/.gems"' >> ~/.bashrc
echo 'export PATH="$HOME/.gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

gem install jekyll bundler
jekyll --version

Linux-Specific Notes: - Installing gems to $GEM_HOME in your home directory avoids needing sudo. - build-essential (or the dev tools group) is required to compile native gems.

☁️ Cloud Realms Path

Click to expand Cloud/Container instructions 
# Run Jekyll in a container - zero local Ruby setup
docker run --rm -it -p 4000:4000 -v "$PWD":/srv/jekyll \
  jekyll/jekyll:4 jekyll serve --host 0.0.0.0

# Or use a GitHub Codespace, which ships Ruby preinstalled

Cloud-Specific Notes: - The container mounts your current directory, so edits on your host appear instantly. - --host 0.0.0.0 is required so the forwarded port reaches your browser.

🧙‍♂️ Chapter 1: The Static Site Generator - What Jekyll Actually Does

Before you build, understand the machine. A static site generator takes source files - Markdown, HTML templates, data, and config - and renders them once into a folder of plain HTML, CSS, and JS. That folder is your website. No database runs at request time; the server just hands over files.

⚔️ Skills You'll Forge in This Chapter

  • The difference between dynamic and static sites
  • The Jekyll input-to-output pipeline
  • Your first scaffolded site

🏗️ Build Your First Site

# Scaffold a brand-new Jekyll site
jekyll new my-castle

# Enter the new site and serve it locally
cd my-castle
bundle exec jekyll serve

# Jekyll prints something like:
#   Server address: http://127.0.0.1:4000/
#   Server running... press ctrl-c to stop.

Open http://127.0.0.1:4000/ in your browser. You are looking at HTML that Jekyll generated from Markdown and templates. Press Ctrl-C to stop the server.

Dynamic vs. static, at a glance:

Dynamic site (e.g. WordPress) Static site (Jekyll)
When is the page built? On every request Once, ahead of time
Needs a database? Yes No
Attack surface Large (DB, PHP, plugins) Tiny (just files)
Hosting cost Server + DB Free file host (GitHub Pages)
Speed Variable Very fast

🔍 Knowledge Check: Static Generation

  • In your own words, when does a Jekyll page get built?
  • Why does a static site have a smaller attack surface?
  • What did jekyll new create that jekyll serve then rendered?

⚡ Quick Wins and Checkpoints

  • Setup Complete: jekyll --version prints a version
  • First Success: You viewed your scaffolded site at localhost:4000

🧙‍♂️ Chapter 2: The Directory Structure - A Map of Your Castle

Every Jekyll site follows a layout of special folders. The leading underscore marks folders Jekyll treats specially.

⚔️ Skills You'll Forge in This Chapter

  • What each special folder and file is for
  • The role of the _site output folder
  • How _config.yml ties it together

🏗️ The Anatomy of a Jekyll Site

my-castle/
├── _config.yml      # Global settings: title, baseurl, plugins, build options
├── Gemfile          # The Ruby gems this site depends on
├── index.md         # The home page (Markdown becomes HTML)
├── _posts/          # Blog posts, named YYYY-MM-DD-title.md
├── _layouts/        # Page skeletons (default.html, post.html)
├── _includes/       # Reusable HTML snippets (header.html, footer.html)
├── _data/           # YAML/JSON/CSV data files you can read in templates
├── assets/          # CSS, JS, images - copied through as-is
└── _site/           # GENERATED OUTPUT - never edit, never commit

The golden rule: you edit the source, never _site. Jekyll wipes and rebuilds _site on every run. Add it to .gitignore:

echo "_site/" >> .gitignore
echo ".jekyll-cache/" >> .gitignore

Here is what a minimal _config.yml looks like:

title: My Castle
description: A site forged in the Web Fundamentals tier
baseurl: ""          # subpath, e.g. "/blog"
url: ""              # full host, e.g. "https://example.com"
markdown: kramdown
plugins:
  - jekyll-feed

🔍 Knowledge Check: Directory Structure

  • Which folder holds the generated website you would deploy?
  • Why should you never edit files inside _site?
  • What naming pattern must files in _posts/ follow?

⚡ Quick Wins and Checkpoints

  • Mapped the castle: You can name what _layouts, _includes, and _data hold
  • Ignored the output: _site/ is in your .gitignore

🧙‍♂️ Chapter 3: Collections & the Build Loop - Bringing It to Life

Posts are just the beginning. Collections let you group any kind of related content - quests, recipes, team members - and Jekyll will render each item with shared logic.

⚔️ Skills You'll Forge in This Chapter

  • Declaring and using a custom collection
  • Adding content with front matter
  • The full build-and-serve workflow

🏗️ Declare a Collection

Add a collection in _config.yml:

collections:
  recipes:
    output: true          # generate a page for each recipe
    permalink: /recipes/:name/

Now create the folder and a first item:

mkdir _recipes

Create _recipes/bread.md. The block between the --- lines is front matter - metadata that controls rendering:

---
title: Hearth Bread
layout: default
prep_time: 20 minutes
---

A simple loaf forged in the castle hearth. Mix flour, water, salt, and yeast.

Now run the build and watch the loop:

# Build once into _site/, with verbose output
bundle exec jekyll build --verbose

# Or serve with live reload so the browser refreshes on every save
bundle exec jekyll serve --livereload --drafts

Visit http://127.0.0.1:4000/recipes/bread/ - Jekyll generated that page from your Markdown plus the default layout. The --drafts flag also renders anything in a _drafts/ folder so you can preview unfinished work.

🔍 Knowledge Check: Collections & Build

  • What does output: true do for a collection?
  • What is front matter, and where does it live in a file?
  • What is the difference between jekyll build and jekyll serve?

🧙‍♂️ Chapter 4: Front Matter as a CMS & Taming the Theme

You have built, mapped, and populated your castle. Now learn the deeper magic: those little blocks of front matter are not just metadata - together with your Markdown files they are your content-management system. No admin panel, no database to back up. Git is your edit history, your editor is your dashboard, and every change is reviewable.

⚔️ Skills You'll Forge in This Chapter

  • Treating version-controlled front matter as a database-free CMS
  • Splitting production and development config so the same repo serves both
  • Diagnosing the three failures every Jekyll builder hits

🏗️ Front Matter Is Your CMS

A traditional CMS stores posts in a database behind a login. Jekyll flips this: each Markdown file is a record, and its front matter is the row of fields. The payoff is concrete:

  • Version control - every edit is a Git commit you can diff, review, and revert.
  • No database - files are trivial to back up, migrate, or move to another generator.
  • Security - no database and no admin login means almost nothing to attack.
  • Portability - the same Markdown works in any static site generator.

To make this CMS trustworthy rather than a pile of loose files, hold to a few practices:

  • Consistent schema - use the same front matter fields across each content type (every recipe has prep_time; every post has date).
  • Validation - check that required fields exist before you build (CI can fail a missing title).
  • Templates - keep a skeleton front matter block per content type so new files start correct.

A VS Code extension like Front Matter CMS gives you a visual editor over exactly these fields - a dashboard for your file-based content, with no server required.

🏗️ One Repo, Two Configs: Dev vs. Production

A real site usually loads its theme one way locally and another way once deployed. Jekyll lets you layer config files so a single repo does both. In _config.yml (used in production, e.g. GitHub Pages) point at a remote theme:

remote_theme: "bamr87/zer0-mistakes"

Then in a _config_dev.yml override, use the locally installed gem instead - faster, and it works offline:

theme: "jekyll-theme-zer0"

Jekyll merges configs left-to-right, so the dev file wins locally while production never sees it:

# Local development - dev overrides win
bundle exec jekyll serve --config _config.yml,_config_dev.yml

# Production build - remote_theme from _config.yml only
JEKYLL_ENV=production bundle exec jekyll build

Prefer zero local Ruby? Run the whole thing in a container:

docker-compose up -d
# Open http://localhost:4002 in your browser

🛠️ Troubleshooting the Three Common Curses

Symptom Cause Cure
cannot load such file -- webrick Ruby 3.0+ dropped webrick from the stdlib bundle add webrick
bundle install fails on a version error Stale Bundler gem install bundler then bundle install
Pages render with no styling Theme not resolved Confirm theme/remote_theme in _config.yml, re-run bundle install, restart the server

🔍 Knowledge Check: CMS & Theme

  • Why can a folder of Markdown files replace a database-backed CMS?
  • What does --config _config.yml,_config_dev.yml let you do that one config can't?
  • Which command fixes a webrick LoadError on Ruby 3.0+?

🎮 Mastery Challenges

🟢 Novice Challenge: Scaffold and Serve

Objective: Create a fresh Jekyll site and view it in your browser.

Requirements: - [ ] Run jekyll new my-site - [ ] Serve it with bundle exec jekyll serve - [ ] Confirm it loads at http://127.0.0.1:4000/

Validation: Run bundle exec jekyll build and confirm a _site/index.html file exists.

🟡 Intermediate Challenge: Add a Custom Collection

Objective: Add a recipes (or quests) collection with at least two items.

Requirements: - [ ] Declare the collection in _config.yml - [ ] Create two Markdown files with front matter - [ ] Confirm each renders at its own permalink

Validation: Both collection pages appear under _site/ and open in the browser.

🔴 Advanced Challenge: Tame the Build

Objective: Configure a reproducible build and a custom home page.

Requirements: - [ ] Pin Jekyll in the Gemfile and commit Gemfile.lock - [ ] Edit index.md to list your collection items - [ ] Add _site/ and .jekyll-cache/ to .gitignore

Validation: bundle exec jekyll build succeeds with no warnings and your home page lists the collection.

🏆 Quest Rewards & Achievements

🎖️ Badges Earned: - 🏆 Site Smith - You built a static site from nothing - 🌱 Sprout of the Static Web - The build-and-serve loop is second nature

🛠️ Skills Unlocked: - Jekyll Project Scaffolding - Stand up a new site in seconds - Static Site Generation Concepts - Reason about source-to-output pipelines

🔓 Unlocked Quests: - GitHub Pages Basics - Put your site online for free - Liquid Templating - Make your pages dynamic at build time - YAML Configuration - Master the config and data files

📊 Progression Points: +50 XP

🗺️ Next Steps in Your Journey

Continue the Main Story: - 🎯 GitHub Pages Basics - Host your Jekyll site for free

Explore Side Adventures: - ⚔️ Liquid Templating - The templating language Jekyll speaks - ⚔️ YAML Configuration - Configure sites and store data

Character Class Recommendations

💻 Software Developer: Continue to GitHub Pages Basics 🏗️ System Engineer: Explore YAML Configuration 🎨 Frontend Specialist: Advance to Liquid Templating

📚 Resources

Official Documentation

Community Resources

Learning Materials

🤝 Quest Completion Checklist

  • ✅ Completed all primary objectives
  • ✅ Built and served a Jekyll site locally
  • ✅ Answered all knowledge check questions
  • ✅ Completed at least one mastery challenge
  • ✅ Explored the resource library
  • ✅ Identified your next quest in the journey

🕸️ Knowledge Graph

Structured wiki-links connect this quest to the IT-Journey knowledge graph. Open the Obsidian Graph View to explore connections.

Level hub: [[Level 0001 - Web Fundamentals]] Overworld: [[🏰 Overworld - Master Quest Map]] Unlocks: [[GitHub Pages Basics]] · [[Liquid Templating]] · [[YAML Configuration]] Obsidian docs: [[Obsidian Knowledge Graph and Wiki Links]]