GEMINI.md

1# Zig Cookbook - Project Context
2 
3## Project Overview
4`zig-cookbook` is a multilingual collection of Zig (0.16.x) programming recipes and examples. It demonstrates common programming tasks using Zig's standard library and specialized packages. The project generates a static documentation website using the [zine](https://zine-ssg.io) static site generator.
5 
6## Key Technologies
7- **Zig (0.16.0)**: The primary programming language.
8- **Zine**: Static site generator for documentation.
9- **Docker**: Used for running databases (Postgres, MySQL) required by some examples.
10- **system dependencies**: Some examples link against C libraries like `libpq`, `mysqlclient`, and `sqlite3`.
11 
12## Directory Structure
13- `assets/src/`: Contains all Zig example source files (e.g., `01-01.zig`).
14- `src/`: Contains localized documentation in Super Markdown (`.smd`) format, organized by language (`en-US`, `zh-CN`).
15- `lib/`: C header files and helper source code for C interop examples.
16- `layouts/`: Templates and UI components for the documentation website.
17- `i18n/`: Internationalization configuration files (`.ziggy`).
18 
19## Building and Running
20The project uses the standard Zig build system.
21 
22### Running Examples
23- **Specific Example**: `zig build run-{chapter}-{seq}` (e.g., `zig build run-01-01`).
24- **All Examples**: `zig build run-all`.
25- **Compile Check**: `zig build check`.
26 
27### Local Documentation
28- **Preview Site**: `make serve` (starts `zine` on port 1313).
29- **Zine Preview**: Alternatively, use `zine` directly.
30 
31### Dependencies & Environment
32- **Install System Libraries**: `make install-deps` (supports macOS via brew and Linux via apt).
33- **Databases**: `docker-compose up -d` to start the required Postgres and MySQL instances.
34- **Environment Variables**: `source env.sh` may be required on some systems to set `PKG_CONFIG_PATH` for database clients.
35 
36## Development Conventions
37- **Zig Version**: Targets Zig 0.16.x. Adheres to modern Zig idioms like `std.Io` and `std.process.Init` entry points.
38- **Testing**: Many examples include `std.testing` assertions within their `main` or as helper blocks to verify correctness.
39- **C Interop**: Uses `b.addTranslateC` in `build.zig` to interface with C libraries.
40- **Formatting**: The project uses `prettier` for linting `.smd` files (via `make lint`).
41 
42## Project-Specific Tips
43- When adding a new recipe:
44  1. Add the Zig code to `assets/src/`.
45  2. Create corresponding `.smd` files in `src/en-US/` and `src/zh-CN/`.
46  3. Update `build.zig` if the example has special library dependencies.
47- Use `std.debug.print` for output in examples as they are meant for learning.
48