Task 2.1 - Building Zola Templates with Codex

TLDR

Used a GPT-5.1 → GPT-5.1-Codex-high pipeline to push my Zola site towards an OpenAI Cookbook-style layout.
Let GPT-5.1 design strict, Codex-ready instructions, then had GPT-5.1-Codex-high apply them to the templates.
Focused AI on boring, obvious layout and template work while I kept full control of structure and taste.
End result: article pages that read more like docs, cleaner templates, and a faster, more repeatable iteration loop.

Task Requirements

I wanted my Zola site to feel closer to the OpenAI Cookbook: narrow, readable content width, clean hierarchy, and decent code styling. I needed to keep all the existing logic, data bindings, and Tera syntax intact while improving layout and typography. The AI piece had to be constrained: everything run via a GPT-5.1 → GPT-5.1-Codex-high pipeline inside VS Code, with diffs and git, and aimed squarely at the menial, time-consuming edits that are obvious but tedious to do by hand.

Goal

The goal was to use a GPT-5.1 → GPT-5.1-Codex-high workflow to offload repetitive, mechanical template editing while I stayed in charge of how the site looks and feels, nudging it towards an OpenAI Cookbook-style experience without surrendering control of the codebase.

Implementation Steps

I first clarified what “Cookbook-like” actually meant for my site: a sensible max content width, clear section spacing, readable headings, and code blocks that don’t look like an afterthought, all layered on top of my existing Zola structure.
I identified the work that was obvious but annoying to do manually—repeated layout tweaks, partial clean-ups, and small consistency fixes across templates—so that AI would only touch the most menial, mechanical parts.
For the key templates (e.g. templates/base.html and article/blog pages), I described the current structure and the target Cookbook-ish style to GPT-5.1, including what must stay intact (bindings, Tera tags, overall block structure).
I had GPT-5.1 turn those descriptions into tight prompts “optimised for Codex”: explicit file paths and blocks, clear instructions like “insert this block above <main>”, hard boundaries on what not to touch, and ordered steps that could be re-run safely.
I fed those prompts into GPT-5.1-Codex-high in VS Code, let it apply the edits to the Zola templates, and reviewed the diffs carefully to confirm that logic and Tera syntax hadn’t been mangled.
When outputs weren’t quite right, I refined the GPT-5.1 prompt rather than dropping back to full manual editing, tightening constraints until GPT-5.1-Codex-high behaved predictably on the same templates.
With the diffs looking sane, I checked the updated pages in the browser for layout and readability, and then committed once the result matched the Cookbook-style target I had in mind.

Notes & Decisions

The core decision was to use AI purely as a workflow optimiser, not as a designer: GPT-5.1 handled abstraction and prompt design, GPT-5.1-Codex-high handled code transformations, and I made all the aesthetic and structural calls. Being explicit about files, blocks, and boundaries was essential; vague prompts are exactly how you get weird, unreviewable changes. This pipeline works because most of the work here is obvious and deterministic—things a human could do but would rather not spend hours on—so letting AI chew through that frees me up to think about the actual experience instead of playing human search-and-replace across templates.

Next Ideas / Follow-ups

None captured yet.