Quick Start Guide

This guide covers all installation methods for the Zer0-Mistakes Jekyll theme.

Choose Your Path

Path A — AI Install Wizard (recommended)

Prerequisites

• Docker Desktop
• Git (optional, but recommended)

1) Full install (default)

Create a new folder and run the installer:

mkdir my-site
cd my-site
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash -s -- --full

A successful run ends with a summary and your next steps:

[SUCCESS] Installation completed successfully!
[INFO] Installation mode: full
[INFO] Next steps:
  1. cd my-site
  2. Review and customize _config.yml
  3. Run 'docker-compose up' or 'bundle install && bundle exec jekyll serve'
  4. Visit http://localhost:4000 to see your site

The full install lays down the complete theme (~500 files: layouts, includes, Sass, assets, Docker config). The --minimal variant writes only the handful of config files below.

Notes:

• --full is the default; it installs the full theme structure, Docker config, and development overrides.
• The installer runs in “remote mode” when it’s executed via curl and downloads the theme files automatically.
• The installer creates a project-local INSTALLATION.md inside the generated site folder.

2) Start the dev server (Docker)

From inside your generated site folder:

docker compose up        # or: docker-compose up (v1 syntax)

The first run builds the image and installs gems, so it takes a few minutes. When it’s ready you’ll see Jekyll’s server line:

       Jekyll Feed: Generating feed for posts
                    done in 4.2 seconds.
 Auto-regeneration: enabled for '/site'
    Server address: http://0.0.0.0:4000
  Server running... press ctrl-c to stop.

Then open http://localhost:4000 — your site is live:

Verify it worked

• The homepage renders with the top navigation bar and a “Get Started” hero.
• Editing any file under pages/ and saving live-reloads the browser.

• A quick build check (run in a second terminal) should exit cleanly:

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

Tip: docker compose (v2, a space) and docker-compose (v1, a hyphen) are interchangeable here. Use whichever your Docker install provides.

3) Minimal install (optional)

If you want a barebones starting point:

mkdir my-site-min
cd my-site-min
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash -s -- --minimal

You can upgrade a minimal install to full later:

curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash -s -- --full

Path B — GitHub Template Repository

One-click to create your own copy of the entire repo.

Option 1: GitHub UI

1. Go to github.com/bamr87/zer0-mistakes
2. Click “Use this template” → “Create a new repository”
3. Clone your new repo and start developing

Option 2: GitHub CLI

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

Note: You must enable “Template repository” in repo Settings → General for this to work.

Path C — GitHub Codespaces (zero-install)

Develop entirely in the cloud — no local Docker or Ruby required.

Option 1: One-click

Option 2: From the repo

1. Go to github.com/bamr87/zer0-mistakes
2. Click Code → Codespaces → Create codespace on main
3. Wait for the environment to build (~2 min)
4. Site auto-starts at port 4000

Option 3: VS Code

1. Install the GitHub Codespaces extension
2. Open Command Palette → Codespaces: Create New Codespace
3. Select bamr87/zer0-mistakes

Path D — Fork/Clone (personal site)

Fork into <your-username>.github.io for a GitHub Pages user site that works out of the box.

Prerequisites

• Docker Desktop
• No existing <your-username>.github.io repository (one free user site per GitHub account)

1) Fork the repo

1. Go to bamr87/zer0-mistakes → Fork
2. Set Repository name to <your-username>.github.io
3. Enable Settings → Pages → Deploy from branch: main
4. Your site goes live at https://<your-username>.github.io

2) Clone and configure locally

git clone https://github.com/<your-username>/<your-username>.github.io.git
cd <your-username>.github.io
./scripts/fork-cleanup.sh   # interactive config wizard

3) Start development (Docker)

docker-compose up

This uses both configs: _config.yml,_config_dev.yml

4) Useful Docker commands

# Rebuild when dependencies change
docker-compose up --build

# Open a shell in the container
docker-compose exec jekyll bash

# Stop containers
docker-compose stop

# Remove containers + network
docker-compose down

See docs/FORKING.md for the full fork → configure → personalize workflow.

Path E — GitHub Pages Remote Theme

Use this if you want your own repo to reference the theme without copying files.

In your site repo’s _config.yml:

remote_theme: "bamr87/zer0-mistakes"
plugins:
  - jekyll-remote-theme

Notes:

• GitHub Pages has a plugin whitelist; keep custom plugins to a minimum.
• Local development via Docker is usually simpler than trying to match GitHub Pages Ruby/Jekyll versions by hand.

Path F — Ruby Gem Theme

Use this if you prefer installing the theme as a gem.

In your Gemfile:

gem "jekyll-theme-zer0"

In your _config.yml:

theme: "jekyll-theme-zer0"

Then:

bundle install
bundle exec jekyll serve --config "_config.yml,_config_dev.yml"

First Personalization Checklist

Most customization starts in _config.yml (production) and _config_dev.yml (development overrides).

1) Update your site identity (_config.yml)

Common fields to change:

• title, subtitle, description
• url and baseurl
• author.* / name / email
• logo / teaser / og_image

Important:

• _config.yml changes are not hot-reloaded by Jekyll; restart your dev server after edits.

2) Disable or replace analytics (_config.yml)

This repo ships with analytics settings (Google Analytics + PostHog). For your own site:

• set google_analytics: null (or your own ID)
• for PostHog, either set posthog.enabled: false or replace posthog.api_key + posthog.api_host

In development, analytics are already disabled in _config_dev.yml.

3) Customize navigation

Navigation data lives under:

• _data/navigation/

If you want to change menus/sidebars, start there, then check:

• _includes/navigation/

4) Add/replace content

Typical content locations:

• index.html / index.md (homepage)
• pages/ (site pages)
• pages/_posts/ (blog posts, if you use posts)
• pages/_docs/ (published end-user documentation)

Troubleshooting

Port already in use

If 4000 is taken, change the host port mapping in docker-compose.yml:

ports:
  - "4001:4000"

Apple Silicon (M-series Macs)

This repo’s Docker config uses platform: linux/amd64 for compatibility. If Docker warns, it’s usually safe to proceed.

Theme not found / remote theme issues

For local Docker development, _config_dev.yml disables remote_theme to avoid requiring GitHub theme fetches.

Config changes don’t show up

• _config.yml changes require restarting the Jekyll server.
• Try:

docker-compose down
docker-compose up

Next Steps

• Theme Guide — Complete customization guide
• Front Matter — Configure page metadata
• Features — Enable Mermaid diagrams, comments, analytics
• Deployment — Publish your site

Technical Reference

For contributor-level details (installer architecture, profile system, deploy target modules):

• Installation Guide → docs/installation/index.md

See also

• [[Getting Started]]
• [[Installation]]
• [[Docker]]
• [[Customization]]