Quick Start Guide

Get your zer0-mistakes Jekyll site running in under 5 minutes. Choose the path that fits your goal:

flowchart TD
    A([Start]) --> B{What's your goal?}
    B --> C[New site, local dev]
    B --> D[Personal GitHub Pages site]
    B --> E[Add theme to existing repo]
    B --> F[Zero-install / cloud]

    C --> C1["Option A: Install wizard\ncurl … | bash + docker compose up"]
    C --> C2["Option B: GitHub Template\ngh repo create --template"]
    D --> D1["Option D: Fork/Clone\ngh repo fork + fork-cleanup.sh"]
    E --> E1["Option E: Remote theme\nremote_theme: bamr87/zer0-mistakes"]
    E --> E2["Option F: Ruby Gem\ngem 'jekyll-theme-zer0'"]
    F --> F1["Option C: Codespaces\nOne click, browser-based"]

Fastest Start (1 command)

mkdir my-site && cd my-site
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
docker compose up

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

Prefer a browser over a terminal? The Site Builder walks you through the same result step by step, with Claude checking your machine, drafting your configuration and content, and starting Docker for you.

What You Get

• Docker environment — consistent dev setup across macOS, Linux, and Windows (WSL)
• Bootstrap 5.3.3 — vendored, responsive, dark-mode-ready
• Live reload — browser updates on every file save
• GitHub Pages compatible — push to main, site deploys automatically
• Privacy-first analytics — PostHog with consent gate, disabled in dev

Installation Options

Option A — Install Wizard

mkdir my-site && cd my-site
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
docker compose up

Option B — GitHub Template

1. Go to github.com/bamr87/zer0-mistakes
2. Click Use this template → Create a new repository
3. Clone your new repo and run docker compose up

Or via CLI:

gh repo create my-site --template bamr87/zer0-mistakes --clone
cd my-site && docker compose up

Option C — GitHub Codespaces

Or: repo page → Code → Codespaces → Create codespace on main.

Option D — Fork/Clone (Personal Site)

Fork into <your-username>.github.io to get your own GitHub Pages site:

gh repo fork bamr87/zer0-mistakes --clone
cd zer0-mistakes
./scripts/fork-cleanup.sh   # interactive config wizard
docker compose up

Enable Pages: Settings → Pages → Branch: main → Save.

See docs/installation/forking.md for the full fork → configure → personalize guide.

Option E — Remote Theme

# _config.yml
remote_theme: "bamr87/zer0-mistakes"
plugins:
  - jekyll-remote-theme

Enable GitHub Pages in your repo’s Settings → Pages.

Option F — Ruby Gem

# Gemfile
gem "jekyll-theme-zer0"

# _config.yml
theme: "jekyll-theme-zer0"

bundle install && bundle exec jekyll serve

Setup Guides

Quick Troubleshooting

Port 4000 in use

lsof -i :4000          # see what's running
docker compose down    # stop any existing containers
docker compose up      # restart

Docker platform warnings (Apple Silicon)

No platform: pin is set — Docker builds your native architecture by default, which is what you want. Forcing linux/amd64 runs the image under QEMU emulation and costs 3–10× on installs and native gem builds. If a third-party tool prints this warning, it is safe to ignore. Export DOCKER_DEFAULT_PLATFORM=linux/amd64 only when you need explicit x86 parity with production.

Jekyll build errors

docker compose exec jekyll bundle exec jekyll doctor
docker compose exec jekyll bundle exec jekyll build --trace

Validate your setup:

docker compose exec -T jekyll bundle exec jekyll build \
  --config '_config.yml,_config_dev.yml'

Need Help?

Start with Machine Setup → if this is your first time, or jump straight to Installation Options to pick your path.