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

For day-to-day local development, run JS watch + Zola serve together:

bun run dev

Open http://127.0.0.1:1111. Re-run bun run index:search when you change chapter HTML or add pages so search stays up to date.

Search UI is available immediately; results require the index step above (static/pagefind/ is gitignored and copied from the build output).

Production build

bun run build

This runs vite build (outputs to themes/openfreebooks/static/js/bundle.js), zola build (outputs to public/), then Pagefind (public/pagefind/).

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.

5.4 KiB Raw Blame History Unescape Escape