- May 19, 2026
- 4 min read
A Free Ebook Library as a Static Site
I’d been writing long-form notes for years: data modelling, self-hosting, IoT, business analysis, running a one-person business. Around the turn of 2026 I turned them into free ebooks, eight of them so far, about a hundred chapters, all on one site.
The goal was boring on purpose: write in Markdown, push, and have a readable, searchable, fast book appear. No PDF pipeline, no ebook store, no CMS.
One book, one folder
Each book is a folder of Markdown files plus a small metadata file listing its chapters in order:
src/content/ebooks/
iot/
_metadata.json title, cover, chapter order
introduction.md
esp32-vs-pico.md
...
dna/
servers/
...
Astro reads them as a content collection, and a single route
(/books/<book>/<chapter>/) renders every chapter of every book. The metadata
decides the order and the previous/next links. If a chapter is listed but
missing, the build warns instead of producing a broken page.
The chapters are plain Markdown on purpose: they read fine on GitHub too.
Charts as code
Technical books need charts, and screenshots of charts go stale. So a chart is a fenced block of JSON, something like:
```chart
{ "type": "pie", "series": [80, 20], "labels": ["vital few", "trivial many"] }
```
The catch: the syntax highlighter sees a code block in an unknown language
called chart and complains. A tiny remark plugin runs first, swaps the
block for a <div> with the JSON in an attribute, and ApexCharts draws it in
the browser:
visit(tree, "code", (node, index, parent) => {
if (node.lang !== "chart") return;
const html = `<div class="ebook-chart" data-config="${encodeURIComponent(node.value)}"></div>`;
parent.children.splice(index, 1, { type: "html", value: html });
});
The data lives in the chapter, next to the text that explains it.
Diagrams and maths
- Mermaid for diagrams, written as text in the chapter.
- KaTeX for equations, via
remark-mathandrehype-katex. The mechanism and data books need real maths, rendered at build time.
Search with no server
A static site can’t run a search backend, and it doesn’t need to. Pagefind
indexes the built pages after astro build and ships the index as static
files. Searching happens in the browser, in WebAssembly.
One gotcha: when I later added a strict Content Security Policy, search
stopped working. The policy blocked WebAssembly from compiling. Allowing
'wasm-unsafe-eval' fixed it, and that permission covers WebAssembly only, not
JavaScript eval.
Links between chapters
This was the bug I didn’t see for a long time. In Markdown, chapters link to each
other as files: see [the next chapter](esp32-vs-pico.md). That works on
GitHub. On the site, each chapter lives at its own URL, so every one of those
links pointed nowhere, and without a 404 page they quietly showed the library
home instead. A site audit eventually
found 273 of them.
The fix is a 60-line remark plugin that runs on every chapter:
- a link to another chapter of the same book becomes
../<chapter>/, keeping any#anchor; - a link to any other relative file (an example script, an unpublished draft) becomes plain text, because it isn’t on the site;
- images, absolute URLs, root paths and anchors are left alone.
The source stays readable on GitHub, and the site has no broken internal links.
It started as a container
The first version ran on my home server, the way I deployed most things then:
- a build stage (Node,
npm install,npm run build); - a runtime container running
serve diston a port; - a compose file putting it on the Cloudflare tunnel’s network;
- analytics settings passed in as build arguments.
It worked. Then I looked at what the runtime container actually did:
serve files from a folder. The site was output: 'static' from day one.
There was no server logic at all.
So the container went from production to development only. The build output now goes straight to Cloudflare Pages:
npm run build && npx wrangler pages deploy dist
| Container at home | Static on Pages | |
|---|---|---|
| Moving parts | image, compose, tunnel, the home server | a folder of files |
| Goes down when | the home server reboots, the disk fills | rarely |
| Cost | electricity, attention | free at this size |
| Global speed | one location | a CDN |
The container is still useful: make docker-up gives a production-like build
locally. It just isn’t what serves readers any more.
Takeaways
- One folder per book, one route for all of them.
- Charts as JSON in Markdown: a remark plugin plus a browser library.
- Static search works: build-time index, browser-side query.
- Fix links where the content is built, not by rewriting the source.
- Ask what your container actually does. If it only serves files, you don’t need it.