zig-cookbook: recipes you can run, not a tutorial you can only read

A cookbook of programs, and a site to read them on

The Zig Cookbook is described as a collection of simple Zig programs that demonstrate good practices to accomplish common programming tasks. The word that matters is programs. A recipe here is code that compiles and runs, not a code fragment in a code block that a reader has to assemble.

The project is published as a website at cookbook.ziglang.cc, generated by zine-ssg, the static site generator for Zig, with a Chinese translation of the README linked from the top of the page. The documentation for the generator says that `zine` will start a server at http://localhost:1990 for preview, and the Makefile in the repository has a `serve` target that starts it on port 1313 with `zine --port 1313`.

The acknowledgements place the project in a line of work. The cookbook was inspired by the Rust Cookbook from the Rust nursery, and the site generator itself was created by Loris Cro, and the README credits both explicitly.

The repository layout is consistent with a documentation site built from a Zig toolchain: `src/` holds the recipe content, `layouts/` the page templates, `i18n/` the localisation data, `assets/` the images, `lib/` shared code, `tests/`, a `build.zig` and `build.zig.zon`, a `docker-compose.yml`, an `env.sh`, and a `zine.ziggy`. There is a `roadmap.md` and an `AGENTS.md` alongside `CLAUDE.md`.

The last push was on 2026-10-01, the repository has no GitHub releases, and the licence file at the root is a special case that is worth reading.

Every recipe has a runnable example

The feature that separates this cookbook from a documentation site is that the examples are part of the build.

Each recipe is accompanied by an illustrative example named after its title, and the README gives the command: `zig build run-{title}`, or `zig build run-all` to execute all of them. The Makefile wraps the second one, with a `run` target that runs `zig build run-all --summary all`.

So a recipe is not a file you read, it is a build target you can run. If you are working through the collection, the difference between running twenty examples and copying twenty snippets into a scratch file is that you find out immediately whether the example still compiles against the current standard library, which in a language moving as fast as Zig is the entire question.

The `--summary all` flag in the Makefile target is a small addition to the README's command, and it is the useful one for a bulk run, because it prints the build summary rather than only the failures.

The `clean` target removes `zig-out` and `zig-cache`, the two directories a Zig build produces, and the `lint` target runs `npx [email protected] --write src`, so the content is formatted with a pinned version of prettier rather than a floating one.

The main branch tracks 0.16.x, and older versions live in other branches

The version policy is stated at the top of the README, in a note: the main branch tracks Zig 0.16.x, and is tested on Linux and macOS via GitHub actions. Earlier Zig support could be found in other branches.

That is a small paragraph and it answers the question that matters most for a cookbook. The recipes show how to do something with the standard library as it is today, and the standard library changes with every release. A branch per language version is the only way to keep the examples honest, and the note tells you to look for the right branch rather than assuming the main branch applies to your toolchain.

The CI setup is visible in the badges: a `ci.yml` workflow for the tests and a `pages.yml` workflow for the site. The listed platform coverage is Linux and macOS, so the examples are not continuously verified on Windows, even though the Makefile has a Windows branch, where the `uname_S` variable is set to Windows rather than being taken from `uname -s`.

The Windows handling appears elsewhere too, in the `install-deps` target, which branches on the same variable to decide which package manager command to use. So Windows is a supported place to work, but not a place the CI is watching.

Some recipes need a database, and the Makefile installs the clients

The README warns that some recipes depend on system libraries, and gives two commands: `make install-deps` to install the client libraries, and `docker-compose up -d` to start the required databases.

The `install-deps` target branches by platform. On macOS it notes in a comment that sqlite3 is preinstalled, and installs `pkgconf`, `libpq` and `mysql-client` with Homebrew. On Linux it installs `pkg-config`, `libsqlite3-dev`, `libpq-dev` and `libmysqlclient-dev` with apt.

The databases come from the compose file, and there are two of them, PostgreSQL and MySQL:

services:
  pg:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: "root"
      MYSQL_DATABASE: public
    ports:
      - "3306:3306"

PostgreSQL 16 on Alpine and MySQL 8.0, both published on their standard ports with a password set through the environment. The MySQL service also creates a database named public, which is a detail that suggests a recipe that connects to it by name.

This is worth pausing on, because it tells you what the collection is reaching for. A cookbook that spins up two database servers and links against the PostgreSQL and MySQL client libraries is not only about strings and arrays, and the set of dependencies is a decent proxy for the set of things the recipes cover.

The `webp` target is a separate piece of tooling, converting the site's images to webp with ImageMagick through `fd` and `convert`, excluding the svg and gif files.

Two licences, and the stricter one covers the text

The licence section is the most consequential line in the README, and it is easy to skim past because it is a single sentence.

The Markdown files are licensed under CC BY-NC-ND 4.0 DEED, and the Zig files are under MIT.

So the code in this repository is permissively licensed and can be copied into a project, while the prose that explains it cannot. CC BY-NC-ND requires attribution, forbids commercial use, and forbids derivatives, which in practice means you cannot take a recipe's text, edit it, and publish the edited version, nor use it in a paid product. The MIT licence on the `.zig` files is unaffected by that.

That split is unusual and it is not a mistake. The text is the substance of a cookbook, and the author has chosen terms that permit reading and sharing it with attribution while keeping it out of commercial reuse, in the way many documentation projects do. The Rust Cookbook is credited in the README as one of the projects that inspired this one.

For anyone who wants the code, this is close to ideal. For anyone who wants to quote the explanations in their own documentation, the answer is in the licence and it is no, unless they get permission.

The localisation section adds one more constraint for contributors: create a corresponding recipe in the language folder, localise it, and submit a pull request. The `i18n/` directory and the language folders in the repository are where that work lands.

Where the Zig Cookbook is the wrong tool

The first wrong case is a commercial project that wants the explanations. The text is CC BY-NC-ND, so it cannot be quoted into commercial documentation or adapted into your own guide. The code is fair game, but a recipe without its explanation is a starting point rather than a solution, and the whole point of the collection is the pairing.

The second is a Zig version other than the one a branch targets. The main branch tracks 0.16.x, and the older branches exist but are not described in the visible README beyond the fact that they are there. Reading a recipe written for a different standard library version means reading the code and spotting what has moved, which is the work the recipe was supposed to save you.

The third is Windows as a continuous integration target. The CI is Linux and macOS, and the Makefile has a Windows branch, so Windows is workable but the examples are not continuously verified there.

The fourth is a reference for the language itself. This is a set of task-shaped recipes, not a specification of the language or a guide to its semantics. The Zig documentation is where the language is described; this is where you find out how someone writes a program that does a particular thing.

The last is a project that expects a versioned, released artefact. There are no GitHub releases, the site is deployed from a branch, and the CI and the site workflow are the visible deployment story. For a collection of examples that you read and copy, that is fine, and for a dependency it would not be.

Editorial conclusion

Adopt the Zig Cookbook as a reference when you are learning Zig and want working, idiomatic examples rather than prose, especially since each recipe is executable with `zig build run-{title}` and the whole set runs with `zig build run-all`. Do not copy its text into a commercial work without checking the licence, because the Markdown is under CC BY-NC-ND 4.0, which forbids derivatives and commercial use, while only the Zig files are MIT. Before you run the examples, note that some recipes need system libraries and databases, so run `make install-deps` and `docker-compose up -d` first, and use the branch matching your Zig version, since the main branch tracks 0.16.x.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. zigcc/zig-cookbook on GitHub