openfreebooks-bookgenerator/.agents/skills/zola/SKILL.md

name	description
zola	Build and maintain the Open Free Books static site with Zola (Tera templates, Sass, content/, data/, theme) and Solid.js frontend. Use when editing zola.toml, content/, themes/openfreebooks/templates/, Sass, static assets, frontend/src/, bundle.js, or running zola build/serve.

Zola (Open Free Books)

Static site: Zola + custom theme openfreebooks. Output goes to public/ (gitignored). Deploy via Wrangler from public/.

Layout

Path	Role
zola.toml	Site config, [extra] URLs for templates
content/	Pages (*.md + front matter, template = "…")
data/	JSON for load_data() (contributors, credits)
static/	Copied to site root (favicons, icons/, etc.)
themes/openfreebooks/templates/	Tera HTML, partials, macros
themes/openfreebooks/sass/	Source styles → compiled public/main.css
themes/openfreebooks/static/js/	Vite output: bundle.js (site chrome) + lazy chunks (e.g. catalog-mermaid-view-*.js)

See reference.md for Tera pitfalls and build checks.

Commands

bun run dev            # instant serve (zola only)
bun run build:chapter math/loci math/measures-dispersion
bun run build:chapter math/*      # wildcard chapter builds
bun run build:chapter             # auto-detect changed chapters (interactive confirm)
bun run build:site                # full site rebuild (includes sponsor sync when token exists)
bun run build                     # alias of build:site
bun test

After Sass or template changes, run zola build (or zola serve). Do not copy public/ into themes/openfreebooks/static/.

Build mode behavior

• Chapter workflow: prefer build:chapter for normal content work; it rebuilds chapter assets and only runs Vite when frontend/site-shell code changes.
• Site workflow: use build:site/build for full rebuilds and release verification.
• CI: use bun run build:site and bun test.

Search (Pagefind): read zola-pagefind.md before changing search UI, indexing, or data-pagefind-* attributes.

Templates (Tera)

• Extend base.html; use {% block content %} for page bodies.
• {% import "macros/….html" as ns %} only in templates that extend a layout (e.g. index.html), not inside {% include %} partials.
• Macro calls use keyword arguments: {{ ns::macro_name(arg=value) }}.
• Prefer partials under templates/partials/; kebab-case filenames.
• Icons: Tabler SVGs in static/icons/social/; inline copies in templates/partials/icons/social/*.html included from macros/social-icons.html.

Data files

{% set data = load_data(path="data/contributors.json", format="json") %}

On Zola 0.22+, use the data/… path (not bare contributors.json at repo root).

New page checklist

1. Add content/your-page.md with title, template = "your-template.html".
2. Add themes/openfreebooks/templates/your-template.html extending base.html.
3. Add Sass in themes/openfreebooks/sass/ and @import in main.scss.
4. Wire footer/nav URLs in zola.toml [extra] if needed.

Styling

• No inline Tailwind; use Sass partials and class="" on elements.
• Design tokens in _tokens.scss; section patterns in _components.scss, _why-sections.scss, etc.
• Grain overlay and dark mode via data-theme + CSS variables.

Solid.js

Client behavior lives in frontend/ and mounts from base.html:

Entry	Mount	Notes
js/bundle.js	main.tsx	Header, theme, homepage, chapter widgets
#catalog-app on /catalog/	catalog-app.tsx in bundle	List / Map / Compare; Map lazy-loads catalog-mermaid-view

When changing frontend/ or adding interactivity, read zola-solid.md before editing JS.

When changing the catalog page, map, or compare doc, read zola-catalog.md.

Search (Pagefind)

• Runs after zola build; indexes live chapter pages only (data-pagefind-body on chapter template).
• UI: global modal (⌘K) + /search/ page. See zola-pagefind.md.

Catalog page

• content/catalog.md → template = "catalog.html"
• templates/catalog.html — #catalog-app, #catalog-data JSON, <template id="catalog-compare-template"> (math compare partial)
• Views: list (default), ?view=tree (Mermaid DAG map), ?view=compare (math curricula doc)
• Map colors: Mermaid theme: "base" + hex themeVariables in frontend/src/lib/catalog-mermaid-theme.ts — not Sass fill on cluster rects (inline SVG wins)
• Full file map, strand header post-render, and verify steps: zola-catalog.md
• Run bun run build:js after any frontend/src/components/catalog-* or frontend/src/lib/catalog-* change

Verify

bun run build

Confirm public/main.css contains new selectors (no stale themes/openfreebooks/static/main.css overriding compile). Confirm HTML under public/ matches templates, not an old themes/openfreebooks/static/index.html.