30 November 2025
I’m doing a December Adventure this year for the second time. The idea is you pick a topic or project, work on it a little each day during December, and log your progress.
My plan for this year is to build a website with examples for the Zig programming language, similar to Go by Example. This is something I’d like to have myself – I found Go by Example very useful when I was new to Go and I’m still pretty new to Zig now, plus the language is still changing.
What I have so far is a set of examples that cover the basic language features. The December Adventure will be mostly about creating a pipeline to transform the code samples into HTML. I have some vague idea of putting together a Makefile and some Ruby code to automate everything… but it’s pretty vague so far :)
I’ll add my daily updates below.
Some finishing touches, and deployed the site! Here it is: zigbyexample.neocities.org
Didn’t have a lot of time today, but I did set up a “make” target to deploy the site.
Added links between examples and made various small improvements along the way. Also added a link to download the whole site for offline use.
Finished the two new examples.
Started on adding two new examples to introduce two Zig-specific concepts: illegal behavior and build modes. The idea of illegal behavior comes up in several other examples, so figured it’s a good idea to introduce it early on. And build modes are closely linked to that.
Finished reviewing & improving the examples. I ended up making lots of small changes; feels like the quality is close to where I’d feel good publishing it and having other people use the site.
Continued reviewing & improving the examples. There’s only one left to do, which is the one on integer operators. I’m saving that one for tomorrow because I might have to just rewrite it – the current one is just too complicated.
Continued going reviewing & improving the examples. Didn’t have a lot of time today because of Christmas duties, but I am making progress :)
Started going through the examples one by one to review & improve the content.
My main task for today was to find a solution for cases where the code block on an example page is too small to fit the code. For source code my solution is to rewrite/reformat the code so that doesn’t happen. But on some pages I’m including compiler output, which I obviously can’t control. The solution I came up with is to break up the grid layout in those cases and just use a full-width code block.
It took some effort to detect those cases and change how the HTML is generated, but I like the result:
I also added an “about” page and a dark mode.
Grouped the examples into chapters, added some missing content, and made some improvements to the formatting.
Various fixes and formatting improvements. Here’s a screenshot:
I didn’t have a lot of time the last week – hence the short updates – but I’m off work for the rest of December so I should have more time from now on.
Added some more unit tests.
Some code cleanup and adding tests and documentation.
Skipped December Adventure today.
Finished my simplified Markdown implementation. Now that I’ve removed the dependency on the Markdown library I used before, the pipeline tool doesn’t have any dependencies anymore :)
Started implementing a simplified variant of Markdown.
Implemented syntax highlighting for Zig code.
For today, just a bit of code cleanup and adding tests.
Some more small improvements, like adding a footer to each page and adding some introductory text to the index page. Now it pretty much looks like I want it to.
Made some tweaks to the CSS. Looks much nicer now! I had to remove the syntax highlighting though, because the HTML it was generating wasn’t quite right. I’ll probably end up implementing it myself – I only want minimal syntax highlighting, so that shouldn’t be too hard.
Go busy with work and skipped a day.
Got a basic grid layout working:
The spacing is not 100% right yet, and there’s some other tweaks I want to make, but I think I’m on the right path here.
Reading up on CSS layouts. Looks like a grid layout is what I need.
I started working on the CSS for the site and quickly realized I don’t know nearly enough about the topic. So my next task will be to spend some time learning about CSS and webdesign. (I think a “grid layout” is what I need, but I’ll find out…)
Extended the build pipeline to run the Zig compiler and includes its output in the generated HTML. I basically have the build logic I wanted; next step will be to figure out the webdesign and make the site look good.
The basic build pipeline works! It translates Zig files into HTML, re-building pages if one of the input files changed.
My original plan was to use make to get the “rebuild
only the files whose inputs changed” logic, but ended up implementing it
myself. It’s pretty simple, actually.
Figured out a plan for how the whole build pipeline should work. In
this version, it’s just a single Go binary – so much for using
make and Ruby :)
Some smaller improvements to the Go code. It can generate the HTML for one example now.
Rewrote the Ruby script in Go. I’m much happier with this version – somehow I thought the Ruby code would be more readable because Ruby is supposed to be better at processing text, but in practice that made less of a difference than I expected.
Bit of a slow start: Started hacking on a Ruby script to transform .zig files to .html, then got a bit frustrated and decided maybe Go is a better choice after all. The good news is that I found two Go libraries that look useful (markdown, chroma) so I’ll start messing with those tomorrow.