I made a Zola theme and now you have to deal with it

2026-04-22T00:00:00+00:00

I spent too many weekends on a Zola theme, and here we are.</p>

</a> What ships in v1</h2> Small pages.</strong> Under 40kb per page on almost every route, fonts excluded. The footer prints the actual number on every load. No tracking pixels, no analytics blob, no cookie banner. Body copy is variable Inter (or Public Sans, on ts.com), headings are Space Grotesk (or Newsreader, ts.com), code is JetBrains Mono. All variable WOFF2, Latin subset, cached for a year.</p> No build step in the consumer repo.</strong> The JS is a Vite bundle that ships from the theme's static/dist/</code> as a committed artifact. Consumer sites don't run pnpm install</code>. If you want to recompile, the theme repo has a justfile.</p> Light and dark, no flash.</strong> Theme preference lives in localStorage</code>. Boot script is inlined in <head></code> and runs before paint, so there's no wrong-theme-flash even on a slow connection. Press t</kbd> to toggle.</p> Command palette on /</code>.</strong> Searches post titles and bodies via Zola's built-in index. Lazy-loads on first keypress, about 3kb on the wire. Ctrl+K</kbd> works too if your muscle memory disagrees with the vim default.</p> Asciinema and KaTeX, pay-per-use.</strong> Both only load on pages that use them. A post with no math pays nothing for KaTeX. A post with no terminal recording pays nothing for asciinema.</p> Mastodon and Bluesky comments.</strong> Opt-in per post, lazy-loaded on scroll-into-view. No third-party script until the reader gets there. No cookies. No consent banner. Live demos: Mastodon</a>, Bluesky</a>.</p> Responsive images out of the box.</strong> The image</code> shortcode emits a srcset</code> with WebP variants via Zola's resize_image()</code> at build time. Optional <dialog></code> lightbox, optional left/right float, all driven by one shortcode.</p> Eleven shortcodes, all documented.</strong> alert, collapsible, em, toc, image, carousel, asciinema, katex, mermaid, project, plus pullquote and epigraph for editorial breaks. Every one has a no-JS fallback. Full demo lives in basalt content/options/</a>.</p> </a> Personas</h2> The thing I rewrote six times is the persona system. Both consumer sites speak the same theme but render hella differently:</p> Token</th> auxdev (this site)</th> timsiggins.com</th></tr></thead> --font-text</code></td> Inter</td> Public Sans</td></tr> --font-display</code></td> Space Grotesk</td> Newsreader</td></tr> --ornament</code></td> ▍ ▍ ▍</code></td> ⁂</code></td></tr> --anchor-glyph</code></td> ❯</code></td> §</code></td></tr> Accent</td> terminal green</td> editorial indigo</td></tr> Pullquote font</td> mono italic</td> serif italic</td></tr> </tbody></table> Both sites import the theme once via SCSS aggregator, then layer their own [extra.persona.]</code> token table for colours and fonts, plus a templates/partials/site-head.html</code> for any inline head injection. That's the whole customisation surface.</p> Two visual identities, one engine. The interesting work is what stays the same.</blockquote></aside> </a> What it costs</h2> Rounded, as served, gzipped:</p> Home page HTML: about 8kb</li> Blog post HTML: about 9kb, plus the post body</li> main.css</code>: about 16kb</li> theme.js</code> (inlined, every page): about 1kb</li> Vite main bundle (deferred, every page): about 4kb</li> Lazy chunks (palette, comments, katex, asciinema): 1-3kb each, only on demand</li> Fonts, first visit: about 110kb across three WOFF2 files, then cached for a year</li> </ul> A cold first visit is comfortably under 200kb. A repeat visit, once fonts are cached, is about 25kb. The site stays in the 512kb.club</a> green tier on every route. If you find a route that doesn't, file an issue.</p> </a> What's on the roadmap</h2> I ship theme updates when I remember to, not on a cadence. Loosely ordered by how much I want each one:</p> A "year in review" archive page.</strong> Group posts by year, sparkline of post frequency, link out. One Tera template and a small SCSS file.</li> Tag-prefix search.</strong> The palette searches title and body; I want a #rust</code>-style prefix that filters on tags too.</li> A "printable" view.</strong> Strip the sidebar, flatten the colours, reflow to a paper width. Mostly for when someone sends me a post and I want it on my Kindle.</li> Webmention sender + receiver.</strong> Mastodon and Bluesky comments are neat; a webmention or two would be neater.</li> </ol> Anything else is a maybe. Repo issues are open.</p> </a> Using it</h2> git</span> clone</span> https://codeberg.org/ttsigg/basalt</span> my-blog-theme</span></span> git</span> clone</span> https://codeberg.org/ttsigg/auxdev.net</span> my-blog</span></span> cd</span> my-blog</span></span> ln</span> -</span>s</span> ../my-blog-theme</span> themes/basalt</span> #</span> symlink for now; submodule wiring on the way</span></span> just</span> setup</span></span> just</span> serve</span></span></code></pre> Point config.toml</code> at yourself, drop your content into content/</code>, and just build</code>. The DEPLOY notes for Codeberg + Cloudflare Workers live in the auxdev repo.</p> If you do something neat with it, let me know.</p> basalt 2026-04-22T00:00:00+00:00 The theme behind this site and behind timsiggins.com</a>. Monospace-accented or editorial depending on the persona, keyboard-friendly, light and dark, small enough to serve from a potato. No framework in the consumer repo. JavaScript off? Everything still works except the command palette and the comment embeds.</p> Source lives at codeberg.org/ttsigg/basalt</a>. The README</a> has install notes; the announcement post</a> covers what shipped in v1.</p> basalt</a></h3> </div> </div> </a> What you get</h2> btop-inspired panes</strong> on the homepage and /now</code>, with a live uptime clock, a reading list, and a tinkering-with card driven by a single data/now.json</code>.</li> Command palette</strong> on /</code>. Searches titles and body text via Zola's built-in index, ships at about 3kb, lazy-loads on first keypress. Ctrl+K</kbd> works too.</li> Light and dark themes</strong> with no flash of wrong theme, ever. Press t</kbd> to toggle.</li> Eleven shortcodes</strong> with full no-JS fallbacks: alert, collapsible, em, toc, image (with float + lightbox), carousel, asciinema, katex, mermaid (markdown fence), project, pullquote, epigraph.</li> Asciinema embeds</strong> with a titlebar that matches the site. Player loads only on pages that use the shortcode.</li> KaTeX</strong> for math. Loaded only on pages that contain math.</li> Mastodon and Bluesky comments</strong>, opt-in per post, lazy-loaded on scroll-into-view.</li> Responsive images</strong> via Zola's resize_image()</code> with multi-width WebP srcset</code> out of the box.</li> MPA View Transitions</strong> for smooth navigation in browsers that support them, gated on prefers-reduced-motion</code>.</li> Persona token system.</strong> Two sites running on this theme look completely different — they swap fonts, colours, ornaments, and editorial chrome via a [extra.persona.]</code> table.</li> Under 40kb per page</strong> on almost every route, fonts included.</li> </ul> </a>auxdev's persona — terminal green, mono accents.</figcaption> </figure> </a>The same homepage in dark mode.</figcaption> </figure> </a> Two personas, one engine</h2> The part that took six rewrites is the persona system. Both consumer sites import basalt's SCSS aggregator once, then layer their own token table:</p> Token</th> auxdev (this site)</th> timsiggins.com</th></tr></thead> --font-text</code></td> Inter</td> Public Sans</td></tr> --font-display</code></td> Space Grotesk</td> Newsreader</td></tr> --ornament</code></td> ▍ ▍ ▍</code></td> ⁂</code></td></tr> --anchor-glyph</code></td> ❯</code></td> §</code></td></tr> Accent</td> terminal green</td> editorial indigo</td></tr> Pullquote chrome</td> mono italic, centered</td> serif italic, large</td></tr> </tbody></table> Same Tera templates, same Vite bundle, two wildly different identities. Adding a third consumer site is a config.toml</code> away.</p> </a> A blog post, light and dark</h2> </a>Blog post, desktop, light theme.</figcaption> </figure> </a>Syntax highlighting via giallo, class-based, paired light and dark themes.</figcaption> </figure> </a> Mobile</h2> Same content, narrower viewport. Sidebar collapses to a top bar; panes stack; the command palette still works on phones with a hardware keyboard.</p> </a></li> </a></li></ul>