Why I built aphid

When my brother and I started converting a classic VW Beetle into an electric car, I set up a blog at Aphid EV to track the project and store our research — work that could easily span a decade or more. It's always useful to have a log to fall back on when you pick up a thread after a year away.

I started with a Jekyll site published to GitHub Pages, but it didn't take long before two distinct kinds of content started pulling in opposite directions:

• Progress posts: build-log entries documenting what we did, what broke, and what we learned.
• Reference pages: research notes on components, wiring diagrams, reverse-engineered protocols — material you want to read across, not through.

Blog posts fit Jekyll perfectly, but the reference material had to be shoehorned into blog form, and I kept going back to edit old posts as I learned more. What I really wanted was a wiki-like knowledge base. I've used Obsidian for years and like the way it lets a body of notes grow over time.

Looking for alternatives

I looked at Hugo and Astro, but nothing felt quite right in terms of features, theming, or workflow. Most static site generators treat every file as either a page or a post — there's no first-class notion of a wiki with its own navigation, backlinks, and cross-linking.

So I went the route of personal software — building a tailored tool for my own needs rather than stretching a general-purpose one to fit. With modern coding agents, the cost of that decision is much lower than it used to be.

Design goals

The core idea is a strict separation between three content types:

• Blog posts — date-sorted, tagged, with author metadata.
• Wiki pages — reference material with a flat slug-based namespace, TOC generation, and backlinks.
• Standalone pages — About, Contact, and similar nav-level pages.

Cross-linking between all three is handled with [[wiki-links]]: write [[glossary]] anywhere and aphid resolves it to whichever file has that filename stem, whether it lives in blog/, wiki/, or pages/. In build mode a broken link is a hard error; in serve mode it renders visibly so writing can continue uninterrupted.

That cross-linking is what forces a two-pass pipeline: the first pass indexes every file to build the slug map, and the second pass renders markdown with all links already resolved.

Tech stack

aphid is written in Rust — fast builds, a single static binary, and straightforward cross-platform CI. The intended workflow is markdown files in git, a Deployment workflow in GitHub Actions, and GitHub Pages for hosting. The same setup should work equally well on GitLab, Codeberg, or any other platform with CI and static hosting.

More on the design and internals is in the wiki. The source is on GitHub.