jekyll-theme-zer0 1.9.0 → 1.9.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +16 -3
- data/README.md +186 -530
- data/_data/content_statistics.yml +5 -5
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: a0fbf9d5b24d94cfa33fdfc169f9143347c1dba770db1a9dcb18172c3d3bc4fa
|
|
4
|
+
data.tar.gz: 7b6f35cbd3a498a5159b83373202e14f6770bdafb6fe24d92f4d5684c7050dde
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2c7a68ee418097a07753435ce25f9c23cb300b0ad3b82db680ed5e6f17eb056a1805ad0a8a7c2e625b613634aa9c6bcac8db2219873e0ce9558543bf61569d5f
|
|
7
|
+
data.tar.gz: 516a1860abac56fe71d4bb7d6d33f01220d20a435e1cc605a9a5e525663cb1dec654d89967429062ff6b67253265e64e9caa25c7cbc1b43de82ce46ae97c3c8c
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.9.2] - 2026-05-29
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- Version bump: patch release
|
|
7
|
+
|
|
8
|
+
### Commits in this release
|
|
9
|
+
- 6e73c5f Update README and content statistics
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
## [1.9.1] - 2026-05-27
|
|
13
|
+
|
|
14
|
+
### Fixed
|
|
15
|
+
- Harden one-line installer path
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
|
|
3
19
|
## [1.9.0] - 2026-05-27
|
|
4
20
|
|
|
5
21
|
### Changed
|
|
@@ -31,9 +47,6 @@
|
|
|
31
47
|
### Changed
|
|
32
48
|
- Version bump: patch release
|
|
33
49
|
|
|
34
|
-
### Commits in this release
|
|
35
|
-
- 41bbd9a chore(gemspec): exclude images and large files from gem packaging
|
|
36
|
-
|
|
37
50
|
|
|
38
51
|
## [Unreleased]
|
|
39
52
|
|
data/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
title: zer0-mistakes
|
|
3
3
|
sub-title: AI-Native Jekyll Theme
|
|
4
4
|
description: AI-native Jekyll theme for GitHub Pages — Docker-first development, AI-powered installation, multi-agent integration (Copilot, Codex, Cursor, Claude), AI preview-image generation, and AIEO content optimization with Bootstrap 5.3.
|
|
5
|
-
version: 1.9.
|
|
5
|
+
version: 1.9.2
|
|
6
6
|
layout: landing
|
|
7
7
|
tags:
|
|
8
8
|
- jekyll
|
|
@@ -20,7 +20,7 @@ categories:
|
|
|
20
20
|
- bootstrap
|
|
21
21
|
- ai-tooling
|
|
22
22
|
created: 2024-02-10T23:51:11.480Z
|
|
23
|
-
lastmod: 2026-05-
|
|
23
|
+
lastmod: 2026-05-29T01:42:45.000Z
|
|
24
24
|
draft: false
|
|
25
25
|
permalink: /
|
|
26
26
|
slug: zer0
|
|
@@ -53,90 +53,107 @@ excerpt: "AI-native Jekyll theme for GitHub Pages — multi-agent ready (Copilot
|
|
|
53
53
|
[](AGENTS.md)
|
|
54
54
|
[](#-aieo-optimized--built-for-ai-citation)
|
|
55
55
|
|
|
56
|
-
#
|
|
56
|
+
# zer0-mistakes
|
|
57
57
|
|
|
58
|
-
###
|
|
58
|
+
### A modern website theme that just works — for blogs, docs, portfolios, and more
|
|
59
59
|
|
|
60
|
-
**
|
|
60
|
+
**Free • Open source • Hosted on GitHub Pages for $0/month • Works on Mac, Windows, and Linux**
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
`zer0-mistakes` is a ready-made website you can publish in **under five minutes**, with no design skills, no servers to manage, and almost nothing to install. Pick a template, write your content in plain text, and push to GitHub — your site is live.
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
If you already know Jekyll, Ruby, Docker, or AI coding agents: the same theme grows with you into a fully programmable platform with self-healing install scripts, multi-agent guidance for Copilot / Cursor / Claude, AI-generated preview images, and automated semantic releases to RubyGems. Beginners can skip those parts entirely.
|
|
65
|
+
|
|
66
|
+
[Get Started in 5 Minutes](#-get-started-in-5-minutes) • [What You Get](#-what-you-get) • [Who It's For](#-who-its-for) • [Advanced & AI Features](#-advanced-features-for-power-users) • [Live Demo](https://zer0-mistakes.com/)
|
|
65
67
|
|
|
66
68
|
---
|
|
67
69
|
|
|
68
|
-
##
|
|
70
|
+
## ✨ What You Get
|
|
69
71
|
|
|
70
|
-
|
|
72
|
+
A complete, professional website out of the box — no design or coding required to start:
|
|
71
73
|
|
|
72
|
-
**
|
|
74
|
+
- 📝 **Pages, posts, and a blog** — write in Markdown, organize with tags and categories
|
|
75
|
+
- 🎨 **Beautiful responsive design** — looks great on phones, tablets, and desktops
|
|
76
|
+
- 🌗 **Light and dark mode** — automatic, with a one-click toggle
|
|
77
|
+
- 🔍 **Built-in site search** — press `/` or `Ctrl/Cmd+K` from anywhere
|
|
78
|
+
- 🧭 **Smart navigation** — sidebar, breadcrumbs, table of contents
|
|
79
|
+
- 🔒 **Privacy-friendly** — cookie consent and GDPR/CCPA compliant analytics already wired up
|
|
80
|
+
- 📊 **Diagrams and math** — Mermaid charts and LaTeX equations work out of the box
|
|
81
|
+
- 📓 **Jupyter notebooks** — drop in `.ipynb` files and they render as posts
|
|
82
|
+
- 🧠 **Obsidian-friendly** — edit your site as an Obsidian vault, `[[wiki-links]]` and all
|
|
83
|
+
- ⚙️ **Free hosting on GitHub Pages** — no servers, no monthly bill
|
|
73
84
|
|
|
74
|
-
|
|
75
|
-
- 🧠 **Multi-agent integration** — Drop-in [`AGENTS.md`](AGENTS.md) + `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.github/prompts/*.prompt.md` + `.cursor/commands/` work with Copilot, Codex, Cursor, Claude Code, Aider, Jules, Continue
|
|
76
|
-
- 🎨 **AI preview-image generation** — Jekyll plugin + script generate OpenAI/DALL·E images for posts missing previews ([`_plugins/preview_image_generator.rb`](_plugins/preview_image_generator.rb))
|
|
77
|
-
- 🤝 **AI-facilitated releases** — Conventional-commit analyzer auto-determines semantic version bumps and writes the changelog ([`scripts/analyze-commits.sh`](scripts/analyze-commits.sh))
|
|
78
|
-
- 🔍 **AIEO-optimized output** — Structured data, entity density, FAQ schema, and definitional precision so AI engines cite your site accurately
|
|
85
|
+
> **Want to see it in action?** Visit the [live demo site](https://zer0-mistakes.com/) — it's built with this exact theme.
|
|
79
86
|
|
|
80
|
-
|
|
81
|
-
graph LR
|
|
82
|
-
subgraph "🎯 Your Goal"
|
|
83
|
-
A[Beautiful Website]
|
|
84
|
-
end
|
|
85
|
-
|
|
86
|
-
subgraph "⚡ zer0-mistakes"
|
|
87
|
-
B[One Command] --> C[Auto-Configure]
|
|
88
|
-
C --> D[Docker Ready]
|
|
89
|
-
D --> E[Live Preview]
|
|
90
|
-
end
|
|
91
|
-
|
|
92
|
-
subgraph "🚀 Result"
|
|
93
|
-
F[Production Site]
|
|
94
|
-
end
|
|
95
|
-
|
|
96
|
-
A --> B
|
|
97
|
-
E --> F
|
|
98
|
-
|
|
99
|
-
style A fill:#e1f5fe
|
|
100
|
-
style F fill:#c8e6c9
|
|
101
|
-
```
|
|
87
|
+
---
|
|
102
88
|
|
|
103
|
-
|
|
89
|
+
## 👥 Who It's For
|
|
104
90
|
|
|
105
|
-
|
|
|
106
|
-
|
|
107
|
-
| **
|
|
108
|
-
| **
|
|
109
|
-
| **
|
|
110
|
-
| **
|
|
111
|
-
| **
|
|
112
|
-
| **AI
|
|
113
|
-
| **AI Content Tooling** | None | **First-class** (AI preview images, AIEO schema, prompt library) |
|
|
114
|
-
| **Release Automation** | Manual versioning | **AI-facilitated** ([commit-analyzer](scripts/analyze-commits.sh) → semantic bump + changelog) |
|
|
115
|
-
| **AI Discoverability** | None | **AIEO-optimized** ([structured data, FAQ schema, entity density](#-aieo-optimized--built-for-ai-citation)) |
|
|
91
|
+
| If you are… | You'll love that… |
|
|
92
|
+
|---|---|
|
|
93
|
+
| **A writer or blogger** | You just write Markdown. The theme handles the design. |
|
|
94
|
+
| **A student or teacher** | You can publish lecture notes, notebooks, and reading lists for free on GitHub Pages. |
|
|
95
|
+
| **A maker, artist, or creator** | You get a portfolio-quality landing page with image galleries and project pages. |
|
|
96
|
+
| **A small business or community** | You ship a polished marketing site without paying for hosting or a CMS. |
|
|
97
|
+
| **A developer or technical team** | You get Docker-first dev, semantic-versioned releases, ES6 navigation modules, design tokens, and a full test suite. |
|
|
98
|
+
| **An AI-assisted builder** | The theme ships with first-class guidance for GitHub Copilot, Cursor, Claude Code, Codex, Aider, and any [agents.md](https://agents.md/)-aware tool. |
|
|
116
99
|
|
|
117
100
|
---
|
|
118
101
|
|
|
119
|
-
## 🚀
|
|
102
|
+
## 🚀 Get Started in 5 Minutes
|
|
120
103
|
|
|
121
|
-
|
|
104
|
+
You only need a free [GitHub account](https://github.com/signup). Pick the path that matches your comfort level:
|
|
122
105
|
|
|
123
|
-
|
|
124
|
-
- **Git** ([download](https://git-scm.com/))
|
|
106
|
+
### Path A — Easiest: Fork on GitHub (no terminal required)
|
|
125
107
|
|
|
126
|
-
|
|
108
|
+
1. Click **[Fork](https://github.com/bamr87/zer0-mistakes/fork)** on the repo page.
|
|
109
|
+
2. Rename your fork to **`<your-username>.github.io`** (this turns it into a free website at that URL).
|
|
110
|
+
3. Go to **Settings → Pages → Build and deployment** and select **Deploy from a branch → `main`**.
|
|
111
|
+
4. Wait ~1 minute. Visit `https://<your-username>.github.io` — your site is live.
|
|
112
|
+
5. Edit `_config.yml` and any `*.md` file directly on GitHub to make it yours.
|
|
127
113
|
|
|
128
|
-
|
|
129
|
-
|
|
114
|
+
### Path B — Three-file starter (still no install)
|
|
115
|
+
|
|
116
|
+
Want the lightest possible setup? Create a new repo with just these three files and push it to GitHub. The theme is loaded over the network — there's nothing to download.
|
|
117
|
+
|
|
118
|
+
```text
|
|
119
|
+
my-site/
|
|
120
|
+
├── _config.yml ← title + remote theme link
|
|
121
|
+
├── Gemfile ← github-pages + jekyll-remote-theme
|
|
122
|
+
└── index.md ← your homepage content
|
|
130
123
|
```
|
|
131
124
|
|
|
132
|
-
|
|
125
|
+
Full file contents and the in-browser setup wizard are in the [Bare-Minimum Starter](#-bare-minimum-starter-3-files-zero-install) section below.
|
|
126
|
+
|
|
127
|
+
### Path C — Local development with Docker
|
|
128
|
+
|
|
129
|
+
If you want a live-reload preview on your own computer, you'll need [Docker Desktop](https://www.docker.com/products/docker-desktop) (free) and [Git](https://git-scm.com/).
|
|
133
130
|
|
|
134
131
|
```bash
|
|
132
|
+
mkdir my-site && cd my-site && curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
|
|
135
133
|
docker-compose up
|
|
136
|
-
#
|
|
134
|
+
# Open http://localhost:4000 in your browser
|
|
137
135
|
```
|
|
138
136
|
|
|
139
|
-
|
|
137
|
+
The installer auto-detects your operating system, sets up Docker, downloads the theme, and recovers from common errors. Total time: 2–5 minutes.
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## ⚡ Why People Pick zer0-mistakes
|
|
142
|
+
|
|
143
|
+
| | Most starter themes | zer0-mistakes |
|
|
144
|
+
|---|---|---|
|
|
145
|
+
| **Setup** | Install Ruby, install Bundler, install Jekyll, hope for the best | One command, or just fork a repo |
|
|
146
|
+
| **Works on Apple Silicon, Windows, Linux** | Sometimes | Always (Docker-first) |
|
|
147
|
+
| **First-time success rate** | ~60% | ~95% (self-healing install) |
|
|
148
|
+
| **Looks good immediately** | Needs CSS tweaking | Bootstrap 5.3 design system, ready to ship |
|
|
149
|
+
| **Hosting cost** | $5–20/month | $0 (GitHub Pages) |
|
|
150
|
+
| **AI coding-agent support** | None | Built-in for Copilot, Cursor, Claude, Codex, Aider |
|
|
151
|
+
| **AI-generated post previews** | None | One-command image generation |
|
|
152
|
+
| **Release & changelog management** | Manual | Automated semantic versioning |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 🎯 Bare-Minimum Starter (3 files, zero install)
|
|
140
157
|
|
|
141
158
|
Don't want to run the installer? You can publish a working site to GitHub
|
|
142
159
|
Pages with **just three files** in your repo. The remote theme provides every
|
|
@@ -184,68 +201,39 @@ title: Home
|
|
|
184
201
|
```
|
|
185
202
|
|
|
186
203
|
Push to a GitHub Pages–enabled repository and visit your site. Until you set
|
|
187
|
-
`site_configured: true`, the home page renders the **welcome layout** —
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
welcome screen is replaced by your own content.
|
|
204
|
+
`site_configured: true`, the home page renders the **welcome layout** — a hero
|
|
205
|
+
card and a full in-browser wizard that generates a personalised `_config.yml`
|
|
206
|
+
you can download. Flip the flag (or fill in `title`/`founder`/`email`) and your
|
|
207
|
+
own content takes over.
|
|
192
208
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## 🧰 Advanced Features for Power Users
|
|
212
|
+
|
|
213
|
+
Everything below is **optional**. Beginners can ignore it and still ship a great site. Developers and AI-assisted builders, this is where `zer0-mistakes` becomes a fully programmable platform.
|
|
214
|
+
|
|
215
|
+
Jump to a topic:
|
|
216
|
+
|
|
217
|
+
- [AI-native workflow](#-ai-native-workflow) — multi-agent guidance, AI install wizard, AI preview images, AIEO discovery
|
|
218
|
+
- [Architecture & technology stack](#-architecture)
|
|
219
|
+
- [Key features in depth](#-key-features) — installer CLI, site scraper, Docker, analytics, search, navigation, dark mode
|
|
220
|
+
- [Installation methods](#-installation-methods) — one-liner, modular CLI, remote theme, fork, Ruby gem
|
|
221
|
+
- [Project structure](#-project-structure)
|
|
222
|
+
- [Migration utility](#️-migration-utility--add-admin-pages-to-an-existing-site)
|
|
223
|
+
- [Development workflow & testing](#-development-workflow)
|
|
224
|
+
- [Deployment options](#-deployment)
|
|
225
|
+
- [Documentation map](#-documentation)
|
|
226
|
+
- [Release system & GitHub Actions automation](#-release-system)
|
|
227
|
+
- [Roadmap](#-roadmap)
|
|
228
|
+
- [AIEO — built for AI citation](#-aieo-optimized--built-for-ai-citation)
|
|
207
229
|
|
|
208
230
|
---
|
|
209
231
|
|
|
210
232
|
## 🤖 AI-Native Workflow
|
|
211
233
|
|
|
212
|
-
|
|
234
|
+
> **Who this is for:** anyone using GitHub Copilot, Cursor, Claude Code, Codex, Aider, Continue, or Jules. If you don't use an AI coding assistant, you can skip this section — the rest of the theme works without any AI configuration.
|
|
213
235
|
|
|
214
|
-
|
|
215
|
-
flowchart LR
|
|
216
|
-
subgraph Install["🤖 AI Install"]
|
|
217
|
-
I1[install.sh<br/>self-healing]
|
|
218
|
-
end
|
|
219
|
-
subgraph Author["🧠 AI Authoring"]
|
|
220
|
-
A1[Copilot]
|
|
221
|
-
A2[Codex]
|
|
222
|
-
A3[Cursor]
|
|
223
|
-
A4[Claude Code]
|
|
224
|
-
A5[Aider]
|
|
225
|
-
end
|
|
226
|
-
subgraph Build["🎨 AI Content"]
|
|
227
|
-
B1[OpenAI<br/>Preview Images]
|
|
228
|
-
B2[AI Frontmatter<br/>Maintainer prompt]
|
|
229
|
-
end
|
|
230
|
-
subgraph Release["🚀 AI Release"]
|
|
231
|
-
R1[Commit Analyzer]
|
|
232
|
-
R2[Auto Changelog]
|
|
233
|
-
R3[Semantic Bump]
|
|
234
|
-
end
|
|
235
|
-
subgraph Discover["🔍 AIEO Discovery"]
|
|
236
|
-
D1[JSON-LD Schema]
|
|
237
|
-
D2[FAQ + Glossary]
|
|
238
|
-
D3[Entity Density]
|
|
239
|
-
end
|
|
240
|
-
|
|
241
|
-
Install --> Author --> Build --> Release --> Discover
|
|
242
|
-
|
|
243
|
-
style Install fill:#e3f2fd
|
|
244
|
-
style Author fill:#f3e5f5
|
|
245
|
-
style Build fill:#fff3e0
|
|
246
|
-
style Release fill:#e8f5e9
|
|
247
|
-
style Discover fill:#fce4ec
|
|
248
|
-
```
|
|
236
|
+
zer0-mistakes treats AI as core infrastructure across **install → author → build → release → discover**. Every layer is wired for **automation, facilitation, and integration** with the AI tools you already use — with one consistent guidance layer in `.github/` and `AGENTS.md` that every major agent picks up automatically.
|
|
249
237
|
|
|
250
238
|
### What's wired for AI
|
|
251
239
|
|
|
@@ -301,69 +289,12 @@ Clone the repo (or fork) and your editor's AI agent will pick up project context
|
|
|
301
289
|
|
|
302
290
|
## 🏗 Architecture
|
|
303
291
|
|
|
304
|
-
|
|
292
|
+
> **Who this is for:** developers, theme customizers, and anyone integrating zer0-mistakes into a larger system. If you only want to publish a blog, you can skip ahead to [Key Features](#-key-features) or [Installation Methods](#-installation-methods).
|
|
305
293
|
|
|
306
|
-
|
|
307
|
-
flowchart TB
|
|
308
|
-
subgraph Input["📝 Content Layer"]
|
|
309
|
-
MD[Markdown Files]
|
|
310
|
-
DATA[YAML Data]
|
|
311
|
-
ASSETS[Static Assets]
|
|
312
|
-
end
|
|
313
|
-
|
|
314
|
-
subgraph Theme["🎨 Theme Layer"]
|
|
315
|
-
LAYOUTS[_layouts/]
|
|
316
|
-
INCLUDES[_includes/]
|
|
317
|
-
SASS[_sass/]
|
|
318
|
-
end
|
|
319
|
-
|
|
320
|
-
subgraph Build["⚙️ Build Layer"]
|
|
321
|
-
JEKYLL[Jekyll Engine]
|
|
322
|
-
PLUGINS[Plugins]
|
|
323
|
-
LIQUID[Liquid Templates]
|
|
324
|
-
end
|
|
325
|
-
|
|
326
|
-
subgraph Output["🌐 Output Layer"]
|
|
327
|
-
HTML[Static HTML]
|
|
328
|
-
CSS[Compiled CSS]
|
|
329
|
-
JS[JavaScript]
|
|
330
|
-
end
|
|
331
|
-
|
|
332
|
-
subgraph Deploy["🚀 Deploy Layer"]
|
|
333
|
-
GHPAGES[GitHub Pages]
|
|
334
|
-
DOCKER[Docker Container]
|
|
335
|
-
CDN[CDN/Custom Host]
|
|
336
|
-
end
|
|
337
|
-
|
|
338
|
-
MD --> JEKYLL
|
|
339
|
-
DATA --> JEKYLL
|
|
340
|
-
ASSETS --> JEKYLL
|
|
341
|
-
|
|
342
|
-
LAYOUTS --> JEKYLL
|
|
343
|
-
INCLUDES --> JEKYLL
|
|
344
|
-
SASS --> JEKYLL
|
|
345
|
-
|
|
346
|
-
JEKYLL --> HTML
|
|
347
|
-
JEKYLL --> CSS
|
|
348
|
-
JEKYLL --> JS
|
|
349
|
-
|
|
350
|
-
HTML --> GHPAGES
|
|
351
|
-
HTML --> DOCKER
|
|
352
|
-
HTML --> CDN
|
|
353
|
-
```
|
|
294
|
+
zer0-mistakes is a layered system: your content (Markdown + YAML) flows through the theme's templates, gets compiled by Jekyll, and is published as a fully static site that any host can serve. Every layer is replaceable without affecting the others.
|
|
354
295
|
|
|
355
296
|
### Technology Stack
|
|
356
297
|
|
|
357
|
-
```mermaid
|
|
358
|
-
pie title Technology Distribution
|
|
359
|
-
"Jekyll (Static Gen)" : 25
|
|
360
|
-
"Bootstrap 5.3 (UI)" : 20
|
|
361
|
-
"Docker (Dev Env)" : 18
|
|
362
|
-
"AI Tooling & Agents" : 15
|
|
363
|
-
"Liquid (Templates)" : 12
|
|
364
|
-
"PostHog (Analytics)" : 10
|
|
365
|
-
```
|
|
366
|
-
|
|
367
298
|
| Layer | Technology | Purpose |
|
|
368
299
|
|-------|-----------|---------|
|
|
369
300
|
| **Framework** | Jekyll 3.9.5 | Static site generation |
|
|
@@ -384,6 +315,15 @@ pie title Technology Distribution
|
|
|
384
315
|
|
|
385
316
|
## ✨ Key Features
|
|
386
317
|
|
|
318
|
+
This is the in-depth tour of what ships out of the box. Each subsection is independent — jump to whatever matters for your project.
|
|
319
|
+
|
|
320
|
+
| Audience | Start with |
|
|
321
|
+
|---|---|
|
|
322
|
+
| New users | [Docker-first dev](#-docker-first-development), [Search](#-site-search-v0180), [Dark mode](#-darklight-mode-toggle), [Legal pages](#-legal--compliance-pages-v0150) |
|
|
323
|
+
| Bloggers / writers | [Mermaid diagrams](#-mermaid-diagram-support), [Obsidian vault](#-obsidian-vault-integration), [Jupyter notebooks](#-jupyter-notebook-support) |
|
|
324
|
+
| Site migrators | [Site Scraper](#-site-scraper--clone-any-website) |
|
|
325
|
+
| Developers / SREs | [Modular installer CLI](#-ai-powered-installation--modular-installer), [Enhanced navigation](#-enhanced-navigation-system-v0170), [Privacy-first analytics](#-privacy-first-analytics) |
|
|
326
|
+
|
|
387
327
|
### 🤖 AI-Powered Installation & Modular Installer
|
|
388
328
|
|
|
389
329
|
Two layers of installation automation:
|
|
@@ -415,57 +355,12 @@ curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.s
|
|
|
415
355
|
|
|
416
356
|
The installer is driven by a single spec file (`.zer0/install.spec.json`) that records every decision — profiles chosen, deploy targets, AI provenance — so the entire setup is reproducible and version-controlled.
|
|
417
357
|
|
|
418
|
-
The ~1,100-line classic `install.sh` provides intelligent platform detection and
|
|
419
|
-
|
|
420
|
-
```mermaid
|
|
421
|
-
flowchart TD
|
|
422
|
-
START([Start Installation]) --> DETECT[Detect Platform]
|
|
423
|
-
DETECT --> CHECK{Prerequisites OK?}
|
|
424
|
-
|
|
425
|
-
CHECK -->|Yes| DOWNLOAD[Download Theme]
|
|
426
|
-
CHECK -->|No| GUIDE[Show Requirements]
|
|
427
|
-
|
|
428
|
-
DOWNLOAD --> CONFIG[Configure Docker]
|
|
429
|
-
CONFIG --> VALIDATE{Build Success?}
|
|
430
|
-
|
|
431
|
-
VALIDATE -->|Yes| DONE([✅ Ready!])
|
|
432
|
-
VALIDATE -->|No| LOGS[Show Error Logs]
|
|
433
|
-
|
|
434
|
-
style START fill:#e3f2fd
|
|
435
|
-
style DONE fill:#c8e6c9
|
|
436
|
-
```
|
|
358
|
+
The ~1,100-line classic `install.sh` provides intelligent platform detection, Docker configuration, prerequisite checks, and error recovery with fallbacks.
|
|
437
359
|
|
|
438
360
|
### 🌐 Site Scraper — Clone Any Website
|
|
439
361
|
|
|
440
362
|
`install init --scrape <URL>` BFS-crawls an existing website and turns it into a fully rendered zer0-mistakes site with zero post-processing:
|
|
441
363
|
|
|
442
|
-
```mermaid
|
|
443
|
-
flowchart LR
|
|
444
|
-
subgraph Crawl["🕷 BFS Crawl"]
|
|
445
|
-
C1[Fetch pages]
|
|
446
|
-
C2[Filter junk URLs]
|
|
447
|
-
C3[Classify page kind]
|
|
448
|
-
end
|
|
449
|
-
subgraph Extract["🔍 Extract"]
|
|
450
|
-
E1[Markdown + metadata]
|
|
451
|
-
E2[Image assets]
|
|
452
|
-
E3[Navigation links]
|
|
453
|
-
end
|
|
454
|
-
subgraph Emit["📄 Emit Jekyll"]
|
|
455
|
-
D1[index.md — home]
|
|
456
|
-
D2[pages/events/*.md]
|
|
457
|
-
D3[pages/news/*.md]
|
|
458
|
-
D4[pages/*.md]
|
|
459
|
-
end
|
|
460
|
-
subgraph Wire["🔧 Wire Site"]
|
|
461
|
-
W1[_data/navigation/main.yml]
|
|
462
|
-
W2[assets/scraped/]
|
|
463
|
-
W3[_config.yml seeded]
|
|
464
|
-
end
|
|
465
|
-
|
|
466
|
-
Crawl --> Extract --> Emit --> Wire
|
|
467
|
-
```
|
|
468
|
-
|
|
469
364
|
| What gets scraped | Where it lands |
|
|
470
365
|
|---|---|
|
|
471
366
|
| Home page | `index.md` with `permalink: /` |
|
|
@@ -488,43 +383,36 @@ Requires only `python3` (stdlib) and `curl` — no `pip` dependencies, no API ke
|
|
|
488
383
|
|
|
489
384
|
### 🐳 Docker-First Development
|
|
490
385
|
|
|
491
|
-
|
|
386
|
+
No Ruby, no Bundler, no Jekyll install on your machine. Docker is the *only* prerequisite, and the same container runs identically on Intel Macs, Apple Silicon, Linux, and Windows/WSL2. The bundled `docker-compose.yml` mounts your project directory into the container, so file edits trigger a live rebuild automatically.
|
|
492
387
|
|
|
493
388
|
```yaml
|
|
494
|
-
# docker-compose.yml
|
|
389
|
+
# docker-compose.yml — that's all you need
|
|
495
390
|
services:
|
|
496
391
|
jekyll:
|
|
497
392
|
image: jekyll/jekyll:latest
|
|
498
|
-
platform: linux/amd64
|
|
499
|
-
command: jekyll serve --config "_config.yml,_config_dev.yml"
|
|
500
|
-
ports: ["4000:4000"]
|
|
393
|
+
platform: linux/amd64 # forces x86 emulation on Apple Silicon for gem compatibility
|
|
394
|
+
command: jekyll serve --config "_config.yml,_config_dev.yml" --livereload
|
|
395
|
+
ports: ["4000:4000", "35729:35729"] # Jekyll + LiveReload
|
|
501
396
|
volumes: ["./:/app"]
|
|
397
|
+
environment:
|
|
398
|
+
JEKYLL_ENV: development
|
|
502
399
|
```
|
|
503
400
|
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
GDPR/CCPA compliant PostHog integration with granular consent:
|
|
401
|
+
Day-to-day commands:
|
|
507
402
|
|
|
508
|
-
```
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
ConsentCheck --> Disabled: DNT Enabled
|
|
514
|
-
ConsentCheck --> ShowBanner: No Consent
|
|
515
|
-
ConsentCheck --> Tracking: Has Consent
|
|
516
|
-
|
|
517
|
-
ShowBanner --> Tracking: Accept
|
|
518
|
-
ShowBanner --> Disabled: Decline
|
|
519
|
-
|
|
520
|
-
Tracking --> DataCollection
|
|
521
|
-
DataCollection --> Anonymize
|
|
522
|
-
Anonymize --> PostHog
|
|
523
|
-
|
|
524
|
-
Disabled --> [*]
|
|
525
|
-
PostHog --> [*]
|
|
403
|
+
```bash
|
|
404
|
+
docker-compose up # start with live reload at http://localhost:4000
|
|
405
|
+
docker-compose exec jekyll bash # drop into the container shell
|
|
406
|
+
docker-compose down -v # clean up volumes and gem cache
|
|
407
|
+
docker-compose down && docker-compose up --build # full rebuild after Gemfile changes
|
|
526
408
|
```
|
|
527
409
|
|
|
410
|
+
A separate [`docker-compose.test.yml`](docker-compose.test.yml) provides an isolated environment for CI-style test runs, and [`docker-compose.prod.yml`](docker-compose.prod.yml) (referenced in the [Deployment](#-deployment) section) builds a production image.
|
|
411
|
+
|
|
412
|
+
### 🔒 Privacy-First Analytics
|
|
413
|
+
|
|
414
|
+
GDPR/CCPA compliant PostHog integration with granular consent: it respects Do Not Track, shows a consent banner, anonymizes data, and only sends events to PostHog after the user opts in.
|
|
415
|
+
|
|
528
416
|
### 📊 Mermaid Diagram Support
|
|
529
417
|
|
|
530
418
|
10+ diagram types with GitHub Pages compatibility:
|
|
@@ -641,24 +529,30 @@ Built-in GDPR/CCPA compliant documentation:
|
|
|
641
529
|
|
|
642
530
|
---
|
|
643
531
|
|
|
644
|
-
## 📦 Installation Methods
|
|
532
|
+
## 📦 Installation Methods — Reference Card
|
|
645
533
|
|
|
646
|
-
|
|
534
|
+
The three beginner paths are already covered in [Get Started in 5 Minutes](#-get-started-in-5-minutes). This section is the technical reference: every supported installation method with its exact command and the situation it fits.
|
|
647
535
|
|
|
648
|
-
|
|
536
|
+
| Method | Command | When to use it |
|
|
537
|
+
|---|---|---|
|
|
538
|
+
| **One-line installer** | `curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh \| bash` | Default. Self-healing, ~95% success rate, macOS / Linux / WSL. Same as Get-Started Path C. |
|
|
539
|
+
| **Modular CLI** | `./scripts/bin/install init --profile full /path/to/site` | Reproducible, spec-driven setup with profiles, deploy plugins, AI wizard, and site scraper. Detailed below. |
|
|
540
|
+
| **Remote theme** | `remote_theme: "bamr87/zer0-mistakes"` in `_config.yml` | Three-file repos. Identical to [Get-Started Path B](#path-b--three-file-starter-still-no-install). |
|
|
541
|
+
| **Fork & deploy** | Fork → rename to `<user>.github.io` → enable Pages | Zero-terminal setup. Identical to [Get-Started Path A](#path-a--easiest-fork-on-github-no-terminal-required). |
|
|
542
|
+
| **Ruby gem dependency** | `gem "jekyll-theme-zer0", "~> 1.9"` in `Gemfile` | When you want a pinned version managed by Bundler instead of the remote theme. |
|
|
649
543
|
|
|
650
|
-
|
|
651
|
-
curl -fsSL https://raw.githubusercontent.com/bamr87/zer0-mistakes/main/install.sh | bash
|
|
652
|
-
```
|
|
544
|
+
> **New in 1.0:** the installer is a modular CLI with subcommands and declarative profiles. The classic `curl \| bash` one-liner still works — it bootstraps the same pipeline. See [docs/installation/](docs/installation/index.md) for the full guide and [docs/installation/migration-from-0.x.md](docs/installation/migration-from-0.x.md) for the 0.x → 1.0 flag mapping.
|
|
653
545
|
|
|
654
|
-
###
|
|
546
|
+
### Modular CLI (the in-depth bits)
|
|
547
|
+
|
|
548
|
+
Clone the repo to use `scripts/bin/install` directly:
|
|
655
549
|
|
|
656
550
|
```bash
|
|
657
551
|
git clone https://github.com/bamr87/zer0-mistakes.git
|
|
658
552
|
./zer0-mistakes/scripts/bin/install help
|
|
659
553
|
./zer0-mistakes/scripts/bin/install init --profile full /path/to/new-site
|
|
660
554
|
./zer0-mistakes/scripts/bin/install deploy github-pages,docker-prod /path/to/new-site
|
|
661
|
-
./zer0-mistakes/scripts/bin/install doctor /path/to/new-site
|
|
555
|
+
./zer0-mistakes/scripts/bin/install doctor /path/to/new-site # health check
|
|
662
556
|
./zer0-mistakes/scripts/bin/install agents /path/to/new-site --all # AI agent guidance
|
|
663
557
|
```
|
|
664
558
|
|
|
@@ -666,25 +560,9 @@ Available subcommands: `init`, `wizard [--ai]`, `agents`, `deploy`, `doctor`, `d
|
|
|
666
560
|
|
|
667
561
|
Key `init` flags: `--profile <name>`, `--scrape <URL>`, `--scrape-depth N` (default 2), `--scrape-max-pages N` (default 25), `--skip-doctor`, `--force`.
|
|
668
562
|
|
|
669
|
-
###
|
|
563
|
+
### Forking workflow
|
|
670
564
|
|
|
671
|
-
|
|
672
|
-
# _config.yml
|
|
673
|
-
remote_theme: "bamr87/zer0-mistakes"
|
|
674
|
-
plugins:
|
|
675
|
-
- jekyll-remote-theme
|
|
676
|
-
```
|
|
677
|
-
|
|
678
|
-
### Method 3: Fork & Deploy as Your Site
|
|
679
|
-
|
|
680
|
-
Fork into `<your-username>.github.io` for a working site in minutes:
|
|
681
|
-
|
|
682
|
-
1. Go to [bamr87/zer0-mistakes](https://github.com/bamr87/zer0-mistakes) → **Fork**
|
|
683
|
-
2. Set repository name to **`<your-username>.github.io`**
|
|
684
|
-
3. Enable **Settings → Pages → Deploy from branch: `main`**
|
|
685
|
-
4. Visit `https://<your-username>.github.io`
|
|
686
|
-
|
|
687
|
-
Then personalize locally:
|
|
565
|
+
After forking, personalize locally:
|
|
688
566
|
|
|
689
567
|
```bash
|
|
690
568
|
git clone https://github.com/<your-username>/<your-username>.github.io.git
|
|
@@ -695,47 +573,11 @@ docker-compose up
|
|
|
695
573
|
|
|
696
574
|
See [docs/FORKING.md](docs/FORKING.md) for the full progressive workflow.
|
|
697
575
|
|
|
698
|
-
### Method 4: Ruby Gem
|
|
699
|
-
|
|
700
|
-
```ruby
|
|
701
|
-
# Gemfile
|
|
702
|
-
gem "jekyll-theme-zer0", "~> 0.21"
|
|
703
|
-
```
|
|
704
|
-
|
|
705
576
|
---
|
|
706
577
|
|
|
707
578
|
## 📁 Project Structure
|
|
708
579
|
|
|
709
|
-
|
|
710
|
-
graph TD
|
|
711
|
-
ROOT[zer0-mistakes/] --> CONFIG[Configuration]
|
|
712
|
-
ROOT --> THEME[Theme Components]
|
|
713
|
-
ROOT --> CONTENT[Content]
|
|
714
|
-
ROOT --> AUTOMATION[Automation]
|
|
715
|
-
|
|
716
|
-
CONFIG --> CFG1[_config.yml]
|
|
717
|
-
CONFIG --> CFG2[_config_dev.yml]
|
|
718
|
-
CONFIG --> CFG3[docker-compose.yml]
|
|
719
|
-
|
|
720
|
-
THEME --> LAYOUTS[_layouts/]
|
|
721
|
-
THEME --> INCLUDES[_includes/]
|
|
722
|
-
THEME --> SASS[_sass/]
|
|
723
|
-
THEME --> ASSETS[assets/]
|
|
724
|
-
|
|
725
|
-
CONTENT --> PAGES[pages/]
|
|
726
|
-
CONTENT --> DATA[_data/]
|
|
727
|
-
CONTENT --> DOCS[docs/]
|
|
728
|
-
|
|
729
|
-
AUTOMATION --> SCRIPTS[scripts/]
|
|
730
|
-
AUTOMATION --> TESTS[test/]
|
|
731
|
-
AUTOMATION --> WORKFLOWS[.github/workflows/]
|
|
732
|
-
|
|
733
|
-
style ROOT fill:#e8f5e9
|
|
734
|
-
style CONFIG fill:#e3f2fd
|
|
735
|
-
style THEME fill:#fff3e0
|
|
736
|
-
style CONTENT fill:#fce4ec
|
|
737
|
-
style AUTOMATION fill:#f3e5f5
|
|
738
|
-
```
|
|
580
|
+
The repository follows Jekyll convention with a few additions for tooling and AI guidance. If you only ever edit content, you'll spend all your time in `pages/` and `_data/`. The rest is here when you need it.
|
|
739
581
|
|
|
740
582
|
### Key Directories
|
|
741
583
|
|
|
@@ -755,7 +597,9 @@ graph TD
|
|
|
755
597
|
|
|
756
598
|
---
|
|
757
599
|
|
|
758
|
-
## 🛠️ Migration Utility
|
|
600
|
+
## 🛠️ Migration Utility — Add Admin Pages to an Existing Site
|
|
601
|
+
|
|
602
|
+
Already running a Jekyll site on zer0-mistakes and want the built-in admin UI? `scripts/migrate.sh` copies the six in-browser admin pages (theme customizer, config editor, navigation editor, collection manager, analytics dashboard, environment inspector) into your target site without touching your content.
|
|
759
603
|
|
|
760
604
|
```bash
|
|
761
605
|
# From the zer0-mistakes repo — install into another site
|
|
@@ -788,33 +632,14 @@ This installs 6 admin pages to `pages/_about/settings/`:
|
|
|
788
632
|
|
|
789
633
|
## 🔄 Development Workflow
|
|
790
634
|
|
|
791
|
-
|
|
792
|
-
gitGraph
|
|
793
|
-
commit id: "Clone/Install"
|
|
794
|
-
branch feature
|
|
795
|
-
checkout feature
|
|
796
|
-
commit id: "Make Changes"
|
|
797
|
-
commit id: "Test Locally"
|
|
798
|
-
checkout main
|
|
799
|
-
merge feature id: "PR Merged"
|
|
800
|
-
commit id: "Auto Version" type: HIGHLIGHT
|
|
801
|
-
commit id: "Gem Published"
|
|
802
|
-
commit id: "GitHub Release"
|
|
803
|
-
```
|
|
635
|
+
> **Who this is for:** contributors and anyone customizing the theme locally. The flow is the same one this repo uses internally — clone, branch, change, test, PR, and the automated release pipeline does the rest.
|
|
804
636
|
|
|
805
637
|
### Daily Development
|
|
806
638
|
|
|
807
639
|
```bash
|
|
808
|
-
#
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
# Make changes (auto-reload enabled)
|
|
812
|
-
# Edit files in _layouts/, _includes/, pages/
|
|
813
|
-
|
|
814
|
-
# Run tests
|
|
815
|
-
./test/test_runner.sh
|
|
816
|
-
|
|
817
|
-
# Commit changes
|
|
640
|
+
docker-compose up # live reload at http://localhost:4000
|
|
641
|
+
# edit _layouts/, _includes/, pages/
|
|
642
|
+
./test/test_runner.sh # run tests
|
|
818
643
|
git commit -m "feat: add new component"
|
|
819
644
|
```
|
|
820
645
|
|
|
@@ -850,75 +675,23 @@ npm run vendor:install # manifest downloads (+ Mermaid copy when node_modules
|
|
|
850
675
|
|
|
851
676
|
## 🚀 Deployment
|
|
852
677
|
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
Fork the repo as `<your-username>.github.io` and enable GitHub Pages:
|
|
856
|
-
|
|
857
|
-
1. Push to `main` branch
|
|
858
|
-
2. GitHub Pages builds automatically
|
|
859
|
-
3. Site deploys to `https://<your-username>.github.io`
|
|
860
|
-
|
|
861
|
-
No workflows or `baseurl` configuration needed. See [docs/FORKING.md](docs/FORKING.md) for details.
|
|
862
|
-
|
|
863
|
-
```mermaid
|
|
864
|
-
sequenceDiagram
|
|
865
|
-
participant Dev as Developer
|
|
866
|
-
participant GH as GitHub
|
|
867
|
-
participant Pages as GitHub Pages
|
|
868
|
-
|
|
869
|
-
Dev->>GH: git push main
|
|
870
|
-
GH->>Pages: Auto-build Jekyll
|
|
871
|
-
Pages-->>Dev: 🌐 Site live at username.github.io
|
|
872
|
-
```
|
|
873
|
-
|
|
874
|
-
### Docker Production
|
|
678
|
+
Three supported targets, in order of recommendation:
|
|
875
679
|
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
```bash
|
|
883
|
-
# Build static site
|
|
884
|
-
docker-compose run --rm jekyll jekyll build
|
|
885
|
-
|
|
886
|
-
# Deploy _site/ to any static host
|
|
887
|
-
```
|
|
680
|
+
| Target | Cost | Setup | Best for |
|
|
681
|
+
|---|---|---|---|
|
|
682
|
+
| **GitHub Pages user site** | Free | Push to `main` of `<username>.github.io` (see [Path A](#path-a--easiest-fork-on-github-no-terminal-required)) | Most users; personal sites, docs, blogs, portfolios |
|
|
683
|
+
| **Docker production image** | Self-hosted | `docker-compose -f docker-compose.prod.yml up -d` | Self-hosted servers, intranet, air-gapped environments |
|
|
684
|
+
| **Custom static host** | Varies | `docker-compose run --rm jekyll jekyll build` → upload `_site/` | Netlify, Vercel, Cloudflare Pages, S3 + CloudFront, Azure Static Web Apps |
|
|
888
685
|
|
|
889
686
|
---
|
|
890
687
|
|
|
891
688
|
## 📚 Documentation
|
|
892
689
|
|
|
893
|
-
|
|
690
|
+
zer0-mistakes documentation is split across three audiences. Pick the layer that matches your task:
|
|
894
691
|
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
SYS[systems/]
|
|
899
|
-
FEAT[features/]
|
|
900
|
-
REL[releases/]
|
|
901
|
-
end
|
|
902
|
-
|
|
903
|
-
subgraph Public["📖 /pages/_docs/"]
|
|
904
|
-
GUIDES[User Guides]
|
|
905
|
-
TUTORIALS[Tutorials]
|
|
906
|
-
REF[Reference]
|
|
907
|
-
end
|
|
908
|
-
|
|
909
|
-
subgraph AI["🤖 .github/"]
|
|
910
|
-
COPILOT[copilot-instructions.md]
|
|
911
|
-
SEED[seed/]
|
|
912
|
-
INSTR[instructions/]
|
|
913
|
-
end
|
|
914
|
-
|
|
915
|
-
Technical -->|Process| Public
|
|
916
|
-
AI -->|Guides| Technical
|
|
917
|
-
|
|
918
|
-
style Technical fill:#e3f2fd
|
|
919
|
-
style Public fill:#e8f5e9
|
|
920
|
-
style AI fill:#fff3e0
|
|
921
|
-
```
|
|
692
|
+
- **`/docs/`** — technical reference for theme contributors (architecture, design system, internals).
|
|
693
|
+
- **`/pages/_docs/`** — published user guides on [zer0-mistakes.com/docs/](https://zer0-mistakes.com/docs/) (tutorials, how-tos, FAQs).
|
|
694
|
+
- **`.github/`** — AI agent guidance ([copilot-instructions.md](.github/copilot-instructions.md), file-scoped instructions, reusable prompts, project seed).
|
|
922
695
|
|
|
923
696
|
### Quick Links
|
|
924
697
|
|
|
@@ -937,47 +710,20 @@ graph LR
|
|
|
937
710
|
|
|
938
711
|
## 🔧 Release System
|
|
939
712
|
|
|
940
|
-
|
|
713
|
+
> **Who this is for:** maintainers of this theme, and anyone who forks it to publish their own gem. The release pipeline is fully automated — one command takes you from "commit on main" to "version published on RubyGems and tagged on GitHub."
|
|
941
714
|
|
|
942
|
-
|
|
943
|
-
flowchart LR
|
|
944
|
-
subgraph Trigger["🎯 Trigger"]
|
|
945
|
-
COMMIT[Commit to main]
|
|
946
|
-
end
|
|
947
|
-
|
|
948
|
-
subgraph Analyze["🔍 Analyze"]
|
|
949
|
-
PARSE[Parse Commits]
|
|
950
|
-
BUMP[Determine Version]
|
|
951
|
-
end
|
|
952
|
-
|
|
953
|
-
subgraph Build["⚙️ Build"]
|
|
954
|
-
CHANGE[Update CHANGELOG]
|
|
955
|
-
VERSION[Bump Version]
|
|
956
|
-
TEST[Run Tests]
|
|
957
|
-
GEM[Build Gem]
|
|
958
|
-
end
|
|
959
|
-
|
|
960
|
-
subgraph Publish["🚀 Publish"]
|
|
961
|
-
RUBYGEMS[Push to RubyGems]
|
|
962
|
-
GHREL[GitHub Release]
|
|
963
|
-
TAG[Git Tag]
|
|
964
|
-
end
|
|
965
|
-
|
|
966
|
-
COMMIT --> PARSE --> BUMP
|
|
967
|
-
BUMP --> CHANGE --> VERSION --> TEST --> GEM
|
|
968
|
-
GEM --> RUBYGEMS --> GHREL --> TAG
|
|
969
|
-
```
|
|
715
|
+
The pipeline analyzes your commit messages (Conventional Commits format), decides whether the next release is a patch / minor / major bump, regenerates `CHANGELOG.md`, updates the version file, runs the test suite, builds the gem, publishes to [RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), pushes a tag, and cuts a GitHub Release with auto-generated notes.
|
|
970
716
|
|
|
971
717
|
### Release Commands
|
|
972
718
|
|
|
973
719
|
```bash
|
|
974
|
-
# Preview release
|
|
975
|
-
|
|
720
|
+
# Preview release (no changes published)
|
|
721
|
+
./scripts/bin/release patch --dry-run
|
|
976
722
|
|
|
977
723
|
# Full release
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
724
|
+
./scripts/bin/release patch # 1.9.1 → 1.9.2
|
|
725
|
+
./scripts/bin/release minor # 1.9.1 → 1.10.0
|
|
726
|
+
./scripts/bin/release major # 1.9.1 → 2.0.0
|
|
981
727
|
```
|
|
982
728
|
|
|
983
729
|
---
|
|
@@ -1004,81 +750,6 @@ All workflows live under [`.github/workflows/`](.github/workflows/).
|
|
|
1004
750
|
|
|
1005
751
|
> 💡 GitHub Pages adds an additional managed `pages-build-deployment` run on every push to `main`.
|
|
1006
752
|
|
|
1007
|
-
### Pipeline Topology
|
|
1008
|
-
|
|
1009
|
-
```mermaid
|
|
1010
|
-
flowchart LR
|
|
1011
|
-
subgraph Devloop["🧑💻 Developer Loop"]
|
|
1012
|
-
PR[Pull Request]
|
|
1013
|
-
PUSH[Push to main]
|
|
1014
|
-
end
|
|
1015
|
-
|
|
1016
|
-
subgraph Continuous["🧪 Continuous Integration"]
|
|
1017
|
-
CI[ci.yml<br/>Comprehensive CI]
|
|
1018
|
-
CODEQL[codeql.yml<br/>Security Scan]
|
|
1019
|
-
TESTLATEST[test-latest.yml<br/>Latest Deps]
|
|
1020
|
-
end
|
|
1021
|
-
|
|
1022
|
-
subgraph Maintenance["🔧 Maintenance"]
|
|
1023
|
-
DEPS[update-dependencies.yml<br/>Weekly Bump]
|
|
1024
|
-
ROADMAP[roadmap-sync.yml<br/>README Sync]
|
|
1025
|
-
NOTEBOOKS[convert-notebooks.yml<br/>.ipynb → .md]
|
|
1026
|
-
end
|
|
1027
|
-
|
|
1028
|
-
subgraph Releaseflow["🚀 Release Pipeline"]
|
|
1029
|
-
BUMP[version-bump.yml<br/>Semantic Bump]
|
|
1030
|
-
RELEASE[release.yml<br/>Gem + GitHub Release]
|
|
1031
|
-
PAGES[pages-build-deployment<br/>GitHub Pages]
|
|
1032
|
-
end
|
|
1033
|
-
|
|
1034
|
-
subgraph Bootstrap["🌱 Bootstrap"]
|
|
1035
|
-
SETUP[setup-template.yml<br/>New Site Setup]
|
|
1036
|
-
end
|
|
1037
|
-
|
|
1038
|
-
PR --> CI
|
|
1039
|
-
PR --> CODEQL
|
|
1040
|
-
PUSH --> CI
|
|
1041
|
-
PUSH --> CODEQL
|
|
1042
|
-
PUSH --> ROADMAP
|
|
1043
|
-
PUSH --> NOTEBOOKS
|
|
1044
|
-
PUSH --> BUMP
|
|
1045
|
-
BUMP -->|tag v*| RELEASE
|
|
1046
|
-
PUSH --> PAGES
|
|
1047
|
-
DEPS -.->|opens PR| PR
|
|
1048
|
-
SETUP -.->|first push| PR
|
|
1049
|
-
|
|
1050
|
-
style Continuous fill:#e3f2fd
|
|
1051
|
-
style Maintenance fill:#fff3e0
|
|
1052
|
-
style Releaseflow fill:#e8f5e9
|
|
1053
|
-
style Bootstrap fill:#f3e5f5
|
|
1054
|
-
```
|
|
1055
|
-
|
|
1056
|
-
### What it looks like
|
|
1057
|
-
|
|
1058
|
-
#### 🗂 Actions overview — every workflow at a glance
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
The Actions tab gives you a real-time activity feed — every push to `main` triggers a coordinated set of workflows that you can audit, re-run, or dispatch manually.
|
|
1063
|
-
|
|
1064
|
-
#### 🚀 Release pipeline — automated gem + GitHub release
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
A single tag (`v0.22.21`) — or one click on **Run workflow** — runs the entire publish pipeline in under two minutes. The job graph makes the dependency chain visible: validate → build → publish to [RubyGems](https://rubygems.org/gems/jekyll-theme-zer0) → cut the [GitHub Release](https://github.com/bamr87/zer0-mistakes/releases). No manual `gem push`, no manual changelog edit, no missed step.
|
|
1069
|
-
|
|
1070
|
-
#### 🧪 Comprehensive CI — parallel quality gates
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
CI fans out across **change detection → fast checks → quality control → matrix test suite → integration tests → build & validate**, with annotations surfacing test failures and deprecations directly in the run summary.
|
|
1075
|
-
|
|
1076
|
-
#### 🚦 Per-workflow run history
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
Each workflow has its own run history with branch filters, status badges, and per-job durations — easy to spot regressions or compare runs across branches.
|
|
1081
|
-
|
|
1082
753
|
### Trigger guide
|
|
1083
754
|
|
|
1084
755
|
Use these to invoke automation without leaving your terminal:
|
|
@@ -1109,8 +780,6 @@ When you fork the theme as a starter, the workflows come with you. To make them
|
|
|
1109
780
|
3. **Disable** [`setup-template.yml`](.github/workflows/setup-template.yml) after the first run — it's a one-shot bootstrap.
|
|
1110
781
|
4. **GitHub Pages** is auto-enabled when you push to `main` if your repo is `<username>.github.io`.
|
|
1111
782
|
|
|
1112
|
-
> 📸 Screenshots above are real runs captured from [github.com/bamr87/zer0-mistakes/actions](https://github.com/bamr87/zer0-mistakes/actions). Re-capture them for your fork by running `./scripts/test/capture-workflow-screenshots.sh` (or just take fresh screenshots) and replacing the files in [`docs/images/workflows/`](docs/images/workflows/).
|
|
1113
|
-
|
|
1114
783
|
---
|
|
1115
784
|
|
|
1116
785
|
## 🗺 Roadmap
|
|
@@ -1161,35 +830,18 @@ gantt
|
|
|
1161
830
|
|
|
1162
831
|
## 🤝 Contributing
|
|
1163
832
|
|
|
1164
|
-
|
|
833
|
+
Contributions of every size are welcome — bug reports, doc tweaks, new components, new layouts, accessibility improvements, translations, or whole new features. Every change in this repo is shipped through the same automated release pipeline described above, so your PR can be merged and live as a published gem within hours.
|
|
1165
834
|
|
|
1166
|
-
|
|
1167
|
-
flowchart LR
|
|
1168
|
-
FORK[Fork Repo] --> BRANCH[Create Branch]
|
|
1169
|
-
BRANCH --> CODE[Make Changes]
|
|
1170
|
-
CODE --> TEST[Run Tests]
|
|
1171
|
-
TEST --> PR[Open PR]
|
|
1172
|
-
PR --> REVIEW[Code Review]
|
|
1173
|
-
REVIEW --> MERGE[Merge! 🎉]
|
|
1174
|
-
|
|
1175
|
-
style MERGE fill:#c8e6c9
|
|
1176
|
-
```
|
|
835
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide. The short version:
|
|
1177
836
|
|
|
1178
837
|
### Quick Contribution
|
|
1179
838
|
|
|
1180
839
|
```bash
|
|
1181
|
-
# Fork and clone
|
|
1182
840
|
gh repo fork bamr87/zer0-mistakes --clone
|
|
1183
841
|
cd zer0-mistakes
|
|
1184
|
-
|
|
1185
|
-
# Create feature branch
|
|
1186
842
|
git checkout -b feature/awesome-feature
|
|
1187
|
-
|
|
1188
|
-
#
|
|
1189
|
-
docker-compose up
|
|
1190
|
-
./test/test_runner.sh
|
|
1191
|
-
|
|
1192
|
-
# Submit PR
|
|
843
|
+
docker-compose up # iterate locally
|
|
844
|
+
./test/test_runner.sh # verify
|
|
1193
845
|
git push origin feature/awesome-feature
|
|
1194
846
|
```
|
|
1195
847
|
|
|
@@ -1210,7 +862,7 @@ git push origin feature/awesome-feature
|
|
|
1210
862
|
|
|
1211
863
|
| Metric | Value |
|
|
1212
864
|
|--------|-------|
|
|
1213
|
-
| **Current Version** | 1.9.
|
|
865
|
+
| **Current Version** | 1.9.2 ([RubyGems](https://rubygems.org/gems/jekyll-theme-zer0), [CHANGELOG](/CHANGELOG)) |
|
|
1214
866
|
| **Documented Features** | 43 ([Feature Registry](https://github.com/bamr87/zer0-mistakes/blob/main/_data/features.yml)) |
|
|
1215
867
|
| **Setup Time** | 2-5 minutes ([install.sh benchmarks](https://github.com/bamr87/zer0-mistakes/blob/main/install.sh)) |
|
|
1216
868
|
| **Documentation Pages** | 70+ ([browse docs](/pages/)) |
|
|
@@ -1221,7 +873,11 @@ git push origin feature/awesome-feature
|
|
|
1221
873
|
|
|
1222
874
|
## 🤖 AIEO-Optimized — Built for AI Citation
|
|
1223
875
|
|
|
1224
|
-
|
|
876
|
+
**Why this matters:** when someone asks ChatGPT, Claude, Gemini, or Perplexity about your topic, you want those models to cite *your* site — and to cite it accurately. AI Engine Optimization (AIEO) is to AI assistants what SEO is to Google: a set of patterns that make your content easier for language models to ingest, attribute, and summarize correctly.
|
|
877
|
+
|
|
878
|
+
zer0-mistakes ships these patterns by default on every page, so you get AI discoverability without changing how you write. Implementation lives in `_includes/seo/` and the structured data partials; nothing you author has to know about it.
|
|
879
|
+
|
|
880
|
+
Key patterns applied (see [glossary entry](https://zer0-mistakes.com/glossary/#aieo) for definitions):
|
|
1225
881
|
|
|
1226
882
|
| AIEO Pattern | Implementation |
|
|
1227
883
|
|---|---|
|
|
@@ -1240,7 +896,7 @@ All AIEO enhancements are backward-compatible, follow existing code style (Boots
|
|
|
1240
896
|
|
|
1241
897
|
## 🙏 Acknowledgments
|
|
1242
898
|
|
|
1243
|
-
Built with these
|
|
899
|
+
Built with these technologies:
|
|
1244
900
|
|
|
1245
901
|
- [Jekyll](https://jekyllrb.com/) — Static site generation
|
|
1246
902
|
- [Bootstrap](https://getbootstrap.com/) — UI framework
|
|
@@ -1261,6 +917,6 @@ And these AI partners that make zer0-mistakes truly AI-native:
|
|
|
1261
917
|
|
|
1262
918
|
**Built with ❤️ — and a little help from our AI partners — for the Jekyll community**
|
|
1263
919
|
|
|
1264
|
-
**v1.9.
|
|
920
|
+
**v1.9.2** • [Changelog](CHANGELOG.md) • [License](LICENSE) • [Contributing](CONTRIBUTING.md) • [AI Agent Guide](AGENTS.md)
|
|
1265
921
|
|
|
1266
922
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
generated_at: '2026-05-
|
|
2
|
+
generated_at: '2026-05-29 00:59:17'
|
|
3
3
|
overview:
|
|
4
4
|
total_posts: 25
|
|
5
5
|
total_pages: 148
|
|
@@ -7,8 +7,8 @@ overview:
|
|
|
7
7
|
total_categories: 55
|
|
8
8
|
total_tags: 254
|
|
9
9
|
total_authors: 5
|
|
10
|
-
total_words:
|
|
11
|
-
average_words_per_post:
|
|
10
|
+
total_words: 106994
|
|
11
|
+
average_words_per_post: 618.5
|
|
12
12
|
published: 173
|
|
13
13
|
drafts: 14
|
|
14
14
|
categories:
|
|
@@ -750,7 +750,7 @@ word_statistics:
|
|
|
750
750
|
type: post
|
|
751
751
|
title: 'Urban Resilience: How Cities Prepare for Extreme Heat'
|
|
752
752
|
README.md:
|
|
753
|
-
words:
|
|
753
|
+
words: 6370
|
|
754
754
|
type: page
|
|
755
755
|
title: zer0-mistakes
|
|
756
756
|
STATS_ENHANCEMENT_SUMMARY.md:
|
|
@@ -1226,7 +1226,7 @@ word_statistics:
|
|
|
1226
1226
|
type: page
|
|
1227
1227
|
title: AGENTS
|
|
1228
1228
|
CHANGELOG.md:
|
|
1229
|
-
words:
|
|
1229
|
+
words: 16978
|
|
1230
1230
|
type: page
|
|
1231
1231
|
title: CHANGELOG
|
|
1232
1232
|
CODE_OF_CONDUCT.md:
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: jekyll-theme-zer0
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 1.9.
|
|
4
|
+
version: 1.9.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Amr Abdel
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2026-05-
|
|
11
|
+
date: 2026-05-29 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: jekyll
|