| .agents/skills | ||
| .github | ||
| content | ||
| data | ||
| docs/research | ||
| frontend/src | ||
| scripts | ||
| static | ||
| themes/openfreebooks | ||
| .gitignore | ||
| bun.lock | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| math-banner.jpg | ||
| package.json | ||
| README.md | ||
| skills-lock.json | ||
| spec.md | ||
| tsconfig.json | ||
| vite.config.ts | ||
| wrangler.jsonc | ||
| zola.toml | ||
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
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.