Quick Start Guide

By Amr

Multiple installation methods for the Zer0-Mistakes Jekyll theme - from AI wizard to manual setup.

Estimated reading time: 5 minutes

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

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

Quick Start Guide

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

---

Choose Your Path

Path	Method	Best For
A	AI Install Wizard	Creating a new site (recommended)
B	GitHub Template Repo	One-click copy of the entire repo
C	GitHub Codespaces	Zero-install cloud development
D	Fork/Clone	Personal site & theme customization
E	Remote Theme	GitHub Pages without copying files
F	Ruby Gem	Traditional Jekyll workflow

---

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

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

Then open:

• http://localhost:4000

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

See also

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