| .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
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.
Use bun run dev:full when you want to force a full chapter sync before starting dev servers.
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
bun run build is smart/incremental for local development:
- first run (or missing cache) behaves like a full build,
- repeat runs skip unchanged steps.
Use bun run build:full for a deterministic full rebuild (recommended for CI/release 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.