Developer Guide

This document explains the repository layout, development commands and how to contribute.

Repository layout (high level)

• cmd/anna - CLI and server (main command)
• pkg/engine - core rendering engine
• pkg/parser - markdown parsing and helpers
• site/ - example site used for docs and dogfooding
• test/ - integration and expected output for tests

Build & run

Build locally:

go build ./...

Run the CLI directly during development:

go run github.com/anna-ssg/anna/v3 -p ./site -s

Run only unit tests:

go test ./pkg/...

Run all tests and race detector:

go test ./... -v -race

Deploy your Anna site

Use the helper script at deploy.sh to fetch the latest release and run Anna against your site directory:

./deploy.sh

The script downloads the latest published release for Linux, extracts the binary, builds your site. Use this in CI workflows like GitHub Actions, Cloudflare Pages, Netlify, etc. to deploy your Anna site.

Benchmarks & profiling

Run benchmarks and generate pprof data using the Makefile:

make bench
# results and pprof files are in the profiles/ or test output directories

While serving you can view pprof endpoints at http://localhost:8000/debug/pprof (see cmd/anna).

Makefile targets

Targets:
  build  : Build anna and render the site
  serve  : Build anna, render and serve the site with live reload
  tests  : Run all tests
  bench  : Run the benchmark and generate pprof files
  clean  : Remove the rendered site directory and test output

Contribution workflow

1. Fork the repository and create a feature branch (eg. feature/foo).
2. Write code, run go fmt ./... and add/update tests.
3. Run go test ./... -v and verify all tests pass.
4. Push your branch and open a Pull Request with a clear description and changelog.

Development tips

• Use go vet and go test -race while developing for correctness.
• Keep changes small and isolated; add tests for new behavior.
• Update site/ when adding features that affect rendering or layouts so the docs can dogfood changes.