• 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-math and rehype-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.

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 dist on 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 homeStatic on Pages
Moving partsimage, compose, tunnel, the home servera folder of files
Goes down whenthe home server reboots, the disk fillsrarely
Costelectricity, attentionfree at this size
Global speedone locationa 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.