Open Free Books

Work in Progress. I am looking for contributors to help build this project. Educators and engineer welcome.

Free, open-source textbooks for every learner — from elementary school through university. The site is fully static, open on GitHub, and deployed to Cloudflare.

Live site: openfreebooks.org

Stack

Layer	Tool
Site generator	Zola
Theme	Custom theme in themes/openfreebooks/
Interactivity	Solid.js (header, marquee, scroll reveal, theme toggle)
JS build	Bun + Vite
Search	Pagefind (post-build index, Component UI)
Hosting	Cloudflare Workers (static assets via Wrangler)

Chapter content is HTML partials in the theme today (not Markdown). Catalog maps use a Mermaid-powered interactive tree view (pan/zoom).

Contributing curriculum, subjects, or chapters? See CONTRIBUTING.md.

Prerequisites

• Zola 0.19+
• Bun (for frontend build)
• Wrangler 4.x (for deploy)

Project layout

content/                 # Pages and sections (Markdown front matter)
data/                    # Catalog + per-subject curriculum JSON
static/                  # Site assets copied to public/ (favicons, _redirects)
themes/openfreebooks/    # Zola theme
  templates/             # HTML (Tera)
  sass/                  # Stylesheets (compiled to main.css)
  static/js/bundle.js    # Built Solid bundle (committed for simple deploys)
frontend/src/            # Solid.js source
public/                  # Zola build output (gitignored) — Wrangler deploy target
wrangler.jsonc           # Cloudflare Workers static assets config

Development

Install JS dependencies:

bun install

Serve locally:

bun run dev

Open http://127.0.0.1:1111.

Search UI is available in local serve; run a build command to refresh the search index (static/pagefind/ is gitignored and copied from build output).

Build commands

bun run build:chapter math/measures-dispersion math/loci
bun run build:chapter math/*
bun run build:chapter   # auto-detect changed chapters, list them, ask for confirmation
bun run build:site      # full site build (includes sponsor sync when GITHUB_TOKEN is set)
bun run build           # alias of build:site

build:chapter updates chapter sync, chapter widget JS (targeted), metadata, site output, and search index.

In non-interactive environments, build:chapter requires explicit chapter arguments.

Testing

bun test

bun test includes curriculum validation.

Deploy to Cloudflare

bun run build
wrangler deploy

The Worker name is openfreebooks (see wrangler.jsonc). Assets are served from public/ with no server-side logic.

Configuration

Site-wide settings live in zola.toml:

• base_url — canonical URL for feeds and absolute links
• [extra] — site_title, github_url, browse_url, search_url, about_url (used in templates and the Solid config block)

Theme notes

The visual design is inspired by manlung.work: paper background with grain, Instrument Serif headings, warm ochre accent (#9a6b2e), and light/dark mode (system preference plus a toggle).

Keep themes/openfreebooks/static/ clean. Only committed built assets belong there (currently js/bundle.js). Do not copy Zola’s public/ output into the theme static/ folder — that pollutes public/js/ on the next build.

Contributor experience — known friction (task list)

These issues make contributions harder than they should be. PRs that fix any item are welcome.

Agent skills

Skill	Path	Use
OFB (this project)	.agents/skills/ofb/SKILL.md	Catalog, curriculum JSON, chapters, product rules
Zola + Solid	.agents/skills/zola/SKILL.md	Templates, Sass, bundle, zola serve

License

Open source — see the repository license file when added.