Skip to content

Documentation

The book uses Zensical, with the same pinned version, theme features, light/dark palettes, code highlighting, and publishing pattern as the roto book.

uv sync
uv run zensical serve
uv run zensical build --clean --strict

The build produces site/. Generated output and caches are ignored by Git. Markdown chapters live in docs/; navigation and theme settings live in zensical.toml.

Maintain examples

Prefer runnable source files over copied snippets. Zensical's snippets extension can include repository files:

```python
from itchy import control, events, looks, sensing, sound
from itchy.control import if_
from itchy import move
"""A real collectible: collision detection, score, hiding, and restart."""
from pathlib import Path

from itchy.game import Command, Costume, Game, Message, Num, Sound, Sprite

assets = Path(__file__).parent / "assets"
player_costume = Costume(assets / "player.svg")
collect_sound = Sound("Collect", assets / "collect.wav")
score = Num("score")
collected = Num("collected")
ready = Message("ready")
reset_player: list[Command] = [move.to(0, 0), score.reset(), events.broadcast(ready)]
prepare_coin: list[Command] = [move.to(80, 0), collected.reset(), looks.show()]
collect_coin: list[Command] = [score.add(1), collected.set(1), sound.play(collect_sound), looks.hide()]

player = Sprite("Player", player_costume, (
    events.on_start(reset_player),
    *move.horizontal_controls(step=10),
))
watch_for_player = control.forever(
    if_(collected.equals(0) & sensing.touching(player)).then_(collect_coin),
)
coin = Sprite("Coin", Costume(assets / "coin.png"), (
    events.on_message(ready, prepare_coin, watch_for_player),
), sounds=(collect_sound,))
game = Game("Logic Playground", (score, collected), (player, coin), messages=(ready,))

```

Keep API claims aligned with checked source and tests. Mark adaptations, missing behavior, and planned features explicitly. Link original Scratch projects and preserve attribution when describing recreations.

GitHub Pages

The Documentation workflow validates pull requests and publishes pushes to main. Only the deployment job receives Pages and identity-token write permissions. In repository Settings → Pages, select GitHub Actions as the build source before the first deployment.

The configured public address is the itchy book. Publication runs through GitHub Actions after a push to main.