mirror of
https://github.com/HananoshikaYomaru/openfreebooks.git
synced 2026-11-13 21:15:54 +00:00
117 lines
5.6 KiB
Markdown
117 lines
5.6 KiB
Markdown
|
||
|
||
|
||
# Open Free Books
|
||
|
||
[](https://deepwiki.com/HananoshikaYomaru/openfreebooks)
|
||
|
||
> 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](https://openfreebooks.org)
|
||
|
||
## Stack
|
||
|
||
| Layer | Tool |
|
||
|-------|------|
|
||
| Site generator | [Zola](https://www.getzola.org/) |
|
||
| Theme | Custom theme in `themes/openfreebooks/` |
|
||
| Interactivity | [Solid.js](https://www.solidjs.com/) (header, marquee, scroll reveal, theme toggle) |
|
||
| JS build | [Bun](https://bun.sh/) + [Vite](https://vite.dev/) |
|
||
| Search | [Pagefind](https://pagefind.app/) (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](CONTRIBUTING.md).
|
||
|
||
## Prerequisites
|
||
|
||
- [Zola](https://www.getzola.org/documentation/getting-started/installation/) 0.19+
|
||
- [Bun](https://bun.sh/) (for frontend build)
|
||
- [Wrangler](https://developers.cloudflare.com/workers/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:
|
||
|
||
```bash
|
||
bun install
|
||
```
|
||
|
||
For day-to-day local development, run JS watch + Zola serve together:
|
||
|
||
```bash
|
||
bun run dev
|
||
```
|
||
|
||
Open [http://127.0.0.1:1111](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
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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](https://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](.agents/skills/ofb/SKILL.md) | Catalog, curriculum JSON, chapters, product rules |
|
||
| **Zola + Solid** | [.agents/skills/zola/SKILL.md](.agents/skills/zola/SKILL.md) | Templates, Sass, bundle, `zola serve` |
|
||
|
||
## License
|
||
|
||
Open source — see the repository license file when added.
|