aphid

aphid 0.3.0

2026-05-19T00:00:00+00:00

aphid 0.3.0 reworks the wiki index into a proper landing page. Categories gain descriptions and icons, the index renders them as cards instead of a flat list, and an optional wiki.md file lets you write introductory text above the cards.

Rich wiki categories

wiki_categories in aphid.toml is no longer a flat list of strings. Each category is now a table with an optional description and icon:

[[wiki_categories]]
name = "Getting Started"
description = "Installation, configuration, and first steps."
icon = "/static/wiki/getting-started.svg"

[[wiki_categories]]
name = "Content"
description = "Writing blog posts, wiki pages, and standalone pages."
icon = "/static/wiki/content.svg"

Field	Required	Description
`name`	yes	Category name, matched against frontmatter `category` values
`description`	no	Short blurb shown on the wiki index card
`icon`	no	Root-relative URL path to an SVG icon

The icon path is root-relative (e.g. "/static/wiki/foo.svg"), consistent with favicon and social_image. Place your SVGs under static/ and reference their served path.

This is a breaking change — the old format:

wiki_categories = ["Getting Started", "Content"]

must be migrated to the array-of-tables form shown above. If you only need names, omit description and icon:

[[wiki_categories]]
name = "Getting Started"

[[wiki_categories]]
name = "Content"

Card-based wiki index

The wiki_index.html template now receives richer category objects:

Variable	Type	Description
`categories[].name`	string	Category name
`categories[].description`	string?	From config
`categories[].icon`	string?	From config
`categories[].pages`	list	Pages in this category (`{title, url}`)

The bundled theme and default theme both render these as cards with the icon, name, description, and a list of page links. Custom themes can use as much or as little of the new data as they like — name and pages are always present, just as before.

The same enriched shape is available in the wiki_categories variable on wiki_page.html, so sidebar navigation can also show icons and descriptions if desired.

Wiki intro page

Create a content/wiki.md (no frontmatter needed) to add introductory content above the category cards on the wiki index. The file is rendered through the full markdown pipeline — wiki-links, syntax highlighting, and all other extensions work as expected.

The rendered HTML is exposed to wiki_index.html as wiki_intro.content:

{% if wiki_intro %}
<div class="wiki-intro">
{{ wiki_intro.content | safe }}
</div>
{% endif %}

This follows the same pattern as home.md and 404.md — a bodyless content file (no frontmatter) whose rendered HTML is injected into the corresponding template.

Upgrading

cargo install aphid --locked --force
aphid --version

The only breaking change is the wiki_categories config format. If you were using the old list form, convert each entry to a [[wiki_categories]] table with a name field. Custom themes that loop over categories on wiki_index.html continue to work unchanged — the name and pages fields keep their previous shape, with description and icon added alongside.

After upgrading, run aphid agent <your-tool> to refresh skill files with the updated configuration documentation.

aphid 0.2.2

2026-05-16T00:00:00+00:00

aphid 0.2.2 ships AI-agent skill files you can drop into any project, plus two theme-side wins: a popularity-sorted tag cloud variable for the home page, and a tag page that groups blog posts and wiki pages separately.

AI-agent skills with `aphid agent`

A new subcommand scaffolds project-level instruction files for AI coding agents:

aphid agent claude     # writes .claude/skills/aphid-content + .claude/skills/aphid-theme
aphid agent copilot    # writes .github/copilot-instructions.md
aphid agent codex      # writes AGENTS.md
aphid agent            # same as `aphid agent codex` — generic AGENTS.md

The files describe everything an agent needs to write content or design a theme for your site: the frontmatter shape for each content type, the markdown extensions aphid supports, the Tera template variables exposed to themes, the layout of the static/ directory, and so on. The reference content is embedded in the aphid binary, so re-running the same command after upgrading aphid refreshes the skill files with any new feature documentation.

For Claude Code, the command writes two distinct skills — aphid-content for writing and aphid-theme for design — so the agent loads only what’s relevant to the task at hand. For other tools it writes a single AGENTS.md or the tool-specific equivalent (.github/copilot-instructions.md for GitHub Copilot, etc.). The generic AGENTS.md is also recognised by Aider, Goose, and current Cursor versions.

aphid new and aphid init accept an --agent <tool> flag to scaffold these files at the same time as the rest of the site:

aphid new my-blog --agent claude
aphid init --agent          # generic AGENTS.md (tool defaults to codex)

The main instructions file is preserved on re-run so you can extend it with project-specific guidance; the per-skill reference files are always overwritten. See CLI reference > aphid-agent for the full command reference, and AI-Assisted Writing / AI-Assisted Design for the content of each skill.

Themes can now render a tag cloud on the home page using a new popular_tags variable on the home.html context:

{% for tag in popular_tags %}
<a href="/tags/{{ tag.slug }}/">{{ tag.name }} ({{ tag.count }})</a>
{% endfor %}

Every tag used across blog and wiki content is included, sorted by descending count then ascending name. Counts match the /tags/ index — a tag’s number is identical wherever it appears on the site. For a top-N cloud, slice with popular_tags | slice(end=20) in Tera; weighting font sizes by count is left as a theme decision.

The bundled docs theme renders the cloud as a “Browse by topic” section under the latest posts on the home page.

Tag pages split blog and wiki content

tag.html used to receive a single mixed posts list. It now receives two:

Variable	Contents
`blog_posts`	All blog posts carrying the tag
`wiki_pages`	All wiki pages carrying the tag

Both share the post-entry shape from blog_index.html. If a tag is exclusive to one kind of content the other list is empty — guard both with a length check:

{% if blog_posts | length > 0 %}
<section>
  <h2>Blog</h2>
  {% for post in blog_posts %}…{% endfor %}
</section>
{% endif %}
{% if wiki_pages | length > 0 %}
<section>
  <h2>Wiki</h2>
  {% for post in wiki_pages %}…{% endfor %}
</section>
{% endif %}

This is the small breaking change in 0.2.2: custom themes that previously looped over posts on tag.html need to switch to the two new variables.

Tag pages no longer paginate

Tag pages used to chunk with posts_per_page and reuse the blog-index pagination.html partial with its chronological “Newer / Older” labels — semantics that fit time-ordered blog content but never wiki references. And in practice tag listings rarely accumulate enough items to need chunking.

So 0.2.2 drops pagination from tag pages entirely. The full list of tagged content is rendered on the canonical /tags/<slug>/ URL — no page/N/ subdirectories — and pagination is no longer present on the tag.html context. The pagination.html include still works elsewhere (the blog index keeps its chronological pagination); it’s just never invoked from tag.html.

If your custom theme guards the include with {% if pagination %}{% include "pagination.html" %}{% endif %} on tag.html, the conditional becomes always-false and the include is silently skipped. Drop the line when you’re next editing the template.

See Themes > tag-html for the full updated variable list and Pagination for how pagination still works on the blog index.

Upgrading

cargo install aphid --locked --force
aphid --version

The only breaking change is tag.html. Bundled themes are already updated. For custom themes:

Replace the posts loop with two guarded sections for blog_posts and wiki_pages.
Drop the {% include "pagination.html" %} line — pagination is no longer set on the context.

Everything else is additive: popular_tags on home.html is opt-in, and aphid agent is a new command that doesn’t touch any existing files until you ask it to. After upgrading, run aphid agent <your-tool> once to refresh any previously-generated skill files with the new feature documentation.

aphid 0.2.1

2026-05-15T00:00:00+00:00

aphid 0.2.1 is a small content-polish release. Five additions, all backward-compatible: deeper wiki-links, stable heading anchors, a cleaner way to point an author at a profile URL, social-card meta tags emitted on every page so shared links get proper previews, and reading-time estimates on blog posts.

Wiki-link anchors

Wiki-links now accept an in-page anchor after the slug:

[[configuration#authors]]
[[configuration#authors|the authors section]]

The anchor text is slugified the same way as auto-generated heading ids, so [[page#Hello World]] resolves to #hello-world. A bare cross-page anchor renders as Page Title > section so the reader knows which page they’re heading to; pipe-alias to override.

Same-page anchors work too:

Jump to [[#summary]].

Backlinks are unaffected — the anchor portion is stripped before the link is recorded, so backlinks still aggregate at page granularity.

Custom heading IDs

Append {#custom-id} to any heading to override its auto-generated anchor:

## Configuration reference {#config-ref}

Renders as <h3 id="config-ref">. Custom ids are used verbatim — no lowercasing, no slug normalization — so {#API_v2.1} stays API_v2.1. Custom and auto ids share the same per-page namespace, so collisions still get -2, -3, … suffixes.

The two features compose. Give a heading a custom id, then target it from elsewhere with [[page#stable-id]] — rephrasing the heading text won’t break the link.

Author `link` field

[[authors]] entries now support an explicit link:

[[authors]]
name = "Alice"
link = "https://alice.example.com"
email = "alice@example.com"

Templates receive author.link as the URL for the author’s profile. When link is unset but email is, author.link falls back to mailto:{email} — matching the previous behaviour, so existing configs keep working unchanged. When neither is set, the author name renders as plain text.

The bundled themes wrap the author avatar and name in <a href="{{ author.link }}"> when present. Custom themes that referenced author.email directly should switch to author.link; the value is the same in the email-only case.

Every page now ships OpenGraph and Twitter card meta tags in the <head> — so a link shared in Slack, Discord, Mastodon, iMessage, Bluesky, etc. renders a preview card instead of a bare URL.

Blog posts mark themselves up as og:type=article and emit article:published_time, article:modified_time, article:author, and article:tag tags from frontmatter. Other pages mark themselves up as og:type=website. Titles, descriptions, and images fall back through page → site config sensibly:

Tag	Blog post source	Other pages
`og:title`	frontmatter `title`	page `title`, then `site_title`
`og:description`	frontmatter `description`	site `description`
`og:image`	frontmatter `image`	site `social_image`
`og:url`	absolute URL of the post	absolute URL of the page

A new optional config field sets the site-wide image fallback:

social_image = "/static/social-card.png"   # root-relative URL or absolute URL

Recommended dimensions are 1200×630 px — the summary_large_image Twitter card format that most platforms render best. When no image is configured anywhere, the card downgrades to summary and the og:image / twitter:image tags are omitted.

Custom themes inherit the behaviour automatically by extending base.html. To override the type or add per-page tags, override the og_type and article_meta blocks — see Themes for the full block list.

Reading time

Blog post templates now receive a reading_time_minutes variable — an integer estimate based on word-count of the body, divided by the assumed reading speed, rounded up (minimum 1). The bundled themes render it inline with the publication date:

<span>{{ reading_time_minutes }} min read</span>

The reading speed defaults to 200 wpm (conservative, suits technical writing with code samples) and is tunable via a new reading_wpm config field — raise it for prose-heavy sites:

reading_wpm = 250

Custom themes can render the variable however they like. See Themes for the full per-template variable list.

Upgrading

cargo install aphid --locked --force
aphid --version

One small config tweak: author image paths no longer get a magic /static/ prefix — write them as /static/authors/alice.jpg (the same convention blog hero images and favicon use). The new social_image follows the same rule. Custom themes that read author.email should also switch to author.link.

aphid 0.2.0

2026-05-07T00:00:00+00:00

aphid 0.2.0 is a theming refresh. Your content builds the same as it did before — blog posts still publish, wiki-links still resolve, URLs are unchanged. What’s changed is which variables show up in which templates, plus a couple of small dev-server quality-of-life wins. If you’re using the bundled themes unmodified, you can upgrade with no edits; if you’ve forked or written your own theme, read on.

Why

Templates used to receive a single per-page context object with every conceivable field on it — author, image, description, category, backlinks, the works. Most fields were blog-only or wiki-only, populated as empty for the kinds that didn’t need them, and gated by {% if … %} in the templates. That meant template authors had to remember which fields were “real” on which page kind, and dead fields silently sat there forever.

This release splits the per-page context into three shapes — one for blog posts, one for wiki pages, one for standalone pages — each carrying only the variables its template actually uses.

Theme changes — what to update

The bundled themes have been updated. If you’ve forked or written your own theme, here’s what to change.

`wiki_page.html` gains `category`

Wiki pages now expose a per-page category variable for templates to render (e.g. as a breadcrumb or header label). Pages without an explicit category in frontmatter fall back to wiki_default_category (default "Other"), so the field is always non-empty.

<header>
    <h1>{{ title }}</h1>
    <p class="wiki-category"><a href="/wiki/">Wiki</a> &rsaquo; {{ category }}</p>
</header>

Existing themes that don’t render category continue to work — you just won’t see it.

`wiki_categories[].name` is now a string, never null

The wiki sidebar grouping (wiki_categories on wiki_page.html, categories on wiki_index.html) used to expose name: string?, requiring templates to fall back to a literal "Other" for the uncategorised group:

<!-- Old -->
<div class="wiki-cat-name">{% if category.name %}{{ category.name }}{% else %}Other{% endif %}</div>

The default is now applied at the renderer using the new wiki_default_category config field. name is always populated, so the conditional collapses:

<!-- New -->
<div class="wiki-cat-name">{{ category.name }}</div>

The old form still works (the {% if %} is just always-true), but you can simplify when convenient.

`backlinks` removed from `blog_post.html`

The v1 scope spec said “Backlinks on wiki pages” — singular. The implementation drifted into populating backlinks on every per-page context, including blog posts. That’s now reverted: backlinks is a wiki_page.html-only variable.

If your blog template renders a backlinks section, drop it. If you don’t, the variable simply isn’t there to use.

`tags` removed from `wiki_page.html`

Wiki frontmatter still accepts tags, and tagged wiki pages still appear on tag listings. But the tags variable is no longer exposed on the wiki page template itself — neither bundled theme rendered it. If you were using it on a custom wiki page, switch to displaying tags on the tag-listing pages instead, or open an issue and we’ll talk about restoring it.

`wiki_categories` removed from `blog_post.html` and `page.html`

The full sidebar grouping was previously exposed on every per-page context but only ever used by wiki_page.html. It’s now only on wiki pages, where it makes sense.

`kind` removed from per-page contexts

The kind variable ("blog" / "wiki" / "page") was redundant — each template is its kind, so no template branched on it. Gone. If yours did, replace with separate templates per kind.

Universal core: `title`, `url`, `content`, `toc`, `contains_mermaid`

These five plus the shared site fields (site_title, nav_pages, socials, favicon_tags, feed_atom_url, feed_rss_url, base_url, version) are present on every page template. Previously toc was wiki+blog only; it’s now also available on page.html so themes can render a table of contents for standalone pages too.

The full per-template variable reference is in Themes.

Frontmatter changes

wiki frontmatter’s title field accepts the same YAML it always has — omit it and the page derives its title from the filename stem.

wiki frontmatter’s category is also unchanged in YAML (still optional). What changed is what the renderer does when it’s omitted: instead of leaving the value empty for templates to handle, the renderer substitutes wiki_default_category (default "Other"), so themes can rely on category always being a real string.

New config field

wiki_default_category = "Other"  # default

Sets the display name for wiki pages without an explicit category. Surfaces both as the page’s own category value and as the heading of the catch-all group on the wiki index. Set this if you’d prefer “Misc” or “Uncategorised” or your own term.

Dev-server quality of life

Two small wins for aphid serve:

Favicon edits hot-reload. Saving a new favicon.png while the server is running now triggers a rebuild that detects the change and re-encodes the icon set. Editing markdown stays as fast as ever — the favicon is only re-encoded when its source actually changed. (Previously, favicon source changes were ignored until you restarted the server.)

Config edits trigger rebuilds. aphid.toml is now watched alongside the content directories, so editing the title, swapping the favicon path, changing posts_per_page or wiki_default_category all trigger a rebuild without a restart. The exception is source_dir / static_dir / theme_dir — changing those still needs a restart, because those are the directories the watcher itself is registered on.

Author profile images

Authors configured in aphid.toml now support an optional image field:

[[authors]]
name = "Alice"
email = "alice@example.com"
image = "authors/alice.jpg"

The image path is relative to your static/ directory (served at /static/); absolute URLs (https://…) also work.

In blog post templates, author is now a struct with .name, .email, and .image instead of a plain string. The bundled themes render a round profile picture next to the author name — when no image is configured, a gray silhouette SVG is shown as a fallback. If the author has an email, the avatar and name are wrapped in a mailto: link.

Breaking: templates that used {{ author }} must update to {{ author.name }}.

Upgrading

cargo install aphid --locked --force
aphid --version

If you use only the bundled themes, that’s it. If you have a custom theme, walk through the Theme changes section above.

aphid 0.1.4

2026-05-06T00:00:00+00:00

aphid 0.1.4 is a polish release. No new features — just fixes for things that tripped people up in practice: broken links in feed readers, images that only worked on the home page, and error messages that didn’t explain what went wrong.

Absolute URLs in feeds

Feed readers fetch content outside the context of your site’s domain, so relative links like /blog/other-post/ are meaningless to them. Both the Atom and RSS feeds now rewrite all href and src attributes in post content to full URLs using base_url from your config. The feed metadata links (self-link, entry permalinks) were already absolute — this fixes the inline content body.

Before: <a href="https://aphid.lhelge.se/wiki/configuration/""> inside <content type="html"> After: <a href="https://your-site.com/wiki/configuration/">

No configuration needed — it uses the base_url you already have.

Relative image path normalization

Writing ![screenshot](static/blog/screenshot.png) (without the leading /) worked on the home page but broke on blog posts and the blog index, because the browser resolved it relative to the current URL path. The markdown pipeline now detects bare relative paths and normalizes them to root-relative (/static/blog/screenshot.png) during rendering. This applies to both links and images, but leaves fragments (#heading), absolute URLs, and mailto: links untouched.

Config validation

base_url must now start with http:// or https://. Previously, setting base_url = "/" (common when testing locally without a domain) silently produced empty-string URLs in feeds and the sitemap after trailing-slash normalization. aphid now fails fast at config load time with a clear message:

Error: invalid config: base_url: must start with http:// or https://, got "/"

Better error for non-UTF-8 files

If a .md file contains invalid UTF-8 bytes (wrong encoding, binary accidentally renamed), the error previously surfaced as a generic I/O failure. It now says exactly what’s wrong:

Error: content/wiki/notes.md is not valid UTF-8

GitHub Action

A reusable composite action is now available for CI deployments. Instead of installing Rust and building from source, reference the action to download a pre-built binary:

- uses: actions/checkout@v4

- uses: LHelge/aphid@main
  with:
    version: 'v0.1.4'  # optional, defaults to latest
    output: '_site'     # optional, defaults to dist

- uses: actions/upload-pages-artifact@v5
  with:
    path: _site

It detects the runner platform automatically and supports Linux (x64, arm64), macOS (arm64), and Windows (x64). See Deployment for a complete Pages workflow example.

Upgrading

cargo install aphid --locked --force
aphid --version

There are no breaking changes from 0.1.3 unless your base_url was already invalid (not starting with http:// or https://). If so, fix it in aphid.toml — the config error will tell you exactly what’s expected.

aphid 0.1.3

2026-05-02T00:00:00+00:00

aphid 0.1.3 is about getting started faster. Instead of creating directories and files by hand, a single command now scaffolds a complete site or adds a new content file with the right frontmatter already in place.

Site scaffolding

Two new commands set up a fresh aphid site from scratch:

aphid new my-blog     # create my-blog/ with everything inside
aphid init            # scaffold in the current directory
aphid init path/to    # scaffold in a specific directory

Both generate a minimal but buildable site: aphid.toml with a title derived from the directory name, a .gitignore for /dist, a starter blog post, a “Getting Started” wiki page, an about page, a home page, and an empty static/ directory. The site is built immediately after scaffolding, so dist/ is ready to serve:

aphid new my-blog
cd my-blog
aphid serve

aphid new fails if the target directory already exists; aphid init fails if the directory already contains an aphid.toml. Both are intentional guard rails — no silent overwrites.

Content creation

Once a site exists, three commands create new content files with valid frontmatter:

aphid blog new "My First Post"
aphid wiki new "Architecture Overview"
aphid page new "Contact"

Each derives the filename slug from the title ("My First Post" → my-first-post). Blog posts are prefixed with today’s date and get the full blog frontmatter (title, slug, author, created, description, tags). Wiki and standalone pages get lighter frontmatter matching their respective types. All three commands check for an existing aphid.toml via the --config flag and write into the configured source_dir.

If a file with the same slug already exists the command fails rather than overwriting — rename or delete the existing file first.

Upgrading

cargo install aphid --locked --force
aphid --version

There are no breaking changes from 0.1.2. The new commands are purely additive — existing sites and workflows are unaffected.

aphid 0.1.2

2026-05-01T00:00:00+00:00

aphid 0.1.2 is a release about everyday writing flow: keeping readers up to date with feeds, keeping listings readable as the archive grows, and keeping half-finished pieces out of the published site until they’re ready.

RSS and Atom feeds

Every build now emits an Atom feed at /feed.xml and an RSS feed at /rss.xml, both linked from every page’s <head> so feed readers can discover them automatically. The feed picks up the newest blog posts, and a new feed_limit setting in aphid.toml controls how many appear:

feed_limit = 20   # default; set to 0 for no limit

Both feeds are generated only in aphid build — aphid serve skips them so dev rebuilds stay fast. See Configuration for the full field list.

Pagination

The blog index and per-tag pages now split into pages of posts_per_page once the listing grows past that count. Page 1 stays at the canonical URL (/blog/, /tags/rust/); subsequent pages live at /blog/page/2/, /tags/rust/page/2/, and so on:

posts_per_page = 10   # default

The full mechanics — URL scheme, the pagination template variable, and the page-1-only treatment for “featured” cards — are in Pagination. Themes get a pagination.html partial that renders prev/next/numeric nav, and the docs theme uses pagination.current == 1 to gate its featured-post layout so page 2 onwards renders every post in the same compact format.

Drafts

Setting draft: true in any content file’s frontmatter excludes it from the build entirely:

---
title: Half-finished thoughts
slug: wip
author: LHelge
created: 2026-05-01
draft: true
---

A draft has no rendered page, no entry in any listing, no presence in the feeds or sitemap, and no nav entry (for standalone pages). Wiki-links pointing at a draft fail to resolve as if the file did not exist on disk — aphid build reports a broken link error and aphid serve warns. There is no preview override; to publish, change the flag to false or remove it. See Frontmatter for the field’s full semantics.

Also in 0.1.2

A handful of smaller things landed alongside the headline features:

Adjacent post nav. Every blog post now shows the previous (newer) and next (older) post at the bottom, with date and title. The values are exposed to templates as newer_post and older_post on the blog post context.
Tag-aware cards. Tag badges on the blog index and home-page cards link to the tag page, not the post — clicking the rest of the card still opens the post.
Tag pages share the blog-index layout. The docs theme used to show tag pages as a thin list; they now use the same compact-card format as the blog index, minus the featured treatment.

Upgrading

cargo install aphid --locked --force
aphid --version

There are no breaking changes from 0.1.1. Existing aphid.toml files keep working — feed_limit and posts_per_page both default sensibly, and draft is opt-in per file.

aphid 0.1.1

2026-04-30T00:00:00+00:00

aphid 0.1.1 is a small follow-up to aphid 0.1.0, focused on the markdown pipeline. The headline adds are Mermaid diagrams rendered client-side and GitHub-style alert blocks. Both are things I wanted while writing the docs you’re reading.

Mermaid diagrams

Fenced blocks tagged mermaid are now rendered as live diagrams in the browser. Source goes in, SVG comes out:

```mermaid
sequenceDiagram
    Browser->>aphid: GET /wiki/markdown/
    aphid->>Browser: HTML + <pre class="mermaid">
    Browser->>Mermaid: parse .mermaid blocks
    Mermaid-->>Browser: SVG diagrams
```

Renders as:

sequenceDiagram
    Browser->>aphid: GET /wiki/markdown/
    aphid->>Browser: HTML + <pre class="mermaid">
    Browser->>Mermaid: parse .mermaid blocks
    Mermaid-->>Browser: SVG diagrams

A few notes on how it’s wired:

The Mermaid runtime is vendored with aphid — no CDN, no third-party request at page load. The bundle ships inside the binary and is written out next to the rest of the theme’s static files.
The <script> only loads on pages that actually contain a mermaid block. Index pages, posts without diagrams, and the 404 page all stay clean.
The build pipeline emits each block as <pre class="mermaid">…source…</pre>, so if JavaScript is disabled the reader still sees the original diagram source rather than a blank space.
Flowcharts, sequence diagrams, class diagrams, state diagrams, gantt charts, ER diagrams, mindmaps, gitgraphs — anything Mermaid supports works. See Mermaid diagrams for a tour of the common diagram types with worked examples, or Markdown for the pipeline detail.

Markdown alerts

The five GitHub-flavoured alert types are recognised at parse time:

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Rendered:

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

Each alert is emitted as <div class="markdown-alert markdown-alert-{type}">, so themes can style the five types independently. Plain blockquotes (> without a [!TYPE] marker) are untouched — there’s no behavioural change to existing content.

Also in 0.1.1

A handful of smaller things landed alongside the two headline features:

Smart punctuation. Straight quotes are converted to curly quotes, -- to en-dashes, --- to em-dashes, and ... to ellipses, all at parse time. Just write natural prose.
Favicon generation. Point favicon in aphid.toml at a single source image and aphid emits the full set of platform icons plus the matching <link> tags injected into every page’s <head>. See Configuration.
robots.txt and sitemap.xml. Both are generated automatically at the site root.

Upgrading

cargo install aphid --locked --force
aphid --version

There are no breaking changes from 0.1.0 — alerts, mermaid, and smart punctuation are all additive at the markdown layer, and existing content renders identically unless it contained a literal ```mermaid block, a > [!TYPE] blockquote, or relied on raw -- / ... in prose.

aphid 0.1.0

2026-04-28T00:00:00+00:00

aphid 0.1.0 is out. This is the first tagged release — enough is working to build and deploy a real site, which is what you’re reading right now.

What’s in the box

The core feature set, the things that make aphid useful rather than just a toy:

Three content types — blog posts, wiki pages, and standalone pages, each with their own frontmatter shape and URL scheme. See Frontmatter for the details.
Wiki-links — [[slug]] and [[slug|Display text]] resolve across all content types. Broken links fail the build in aphid build and render visibly in aphid serve. Full details in Wiki Links.
Two-pass pipeline — a first pass indexes every file to build the slug map and backlink graph, then a second pass renders all pages in parallel via rayon.
Syntax highlighting — fenced code blocks are highlighted with syntect using CSS classes, so colors are controlled entirely by the theme stylesheet. See Markdown.
Auto heading anchors — every heading gets a slug-based id attribute. Duplicate headings on the same page get -2, -3 suffixes.
Tag index pages — blog posts can be tagged, and aphid generates a page per tag plus a tags index.
Backlinks — wiki pages show which other pages link to them.
Dev server with live reload — aphid serve runs an axum server with file watching and WebSocket-driven browser refresh. See Dev server.
Embedded default theme — a fresh project needs only aphid.toml and a content/ directory. The default theme is compiled into the binary. Override it by setting theme_dir. See Themes.
Clean URLs — content/wiki/foo.md is served at /wiki/foo/, backed by dist/wiki/foo/index.html.
GitHub Pages deployment — aphid build produces a self-contained output directory ready for any static host. See Deployment for a ready-made GitHub Actions workflow.

What’s not in 0.1.0

Some things are deliberately deferred:

Drafts — no draft: true support yet. Everything in content/ is published.
RSS / Atom feeds — planned but not v1.
Pagination — the blog index and tag pages list all posts on a single page.
Search — no client-side search. The wiki is small enough that the index page and cross-links cover navigation for now.
aphid init — a scaffolding command to set up a clean project, similar to cargo init.
Mermaid diagrams — render mermaid fenced code blocks as diagrams.
Math — Render TeX strings as math expressions.
Sitemap generation — emit a sitemap.xml for search engines.
Open Graph / SEO meta tags — templates should emit <meta og:*> tags from existing frontmatter fields like description and image.
…and more.

Try it

cargo install aphid --locked
aphid --version

Create an aphid.toml, add some markdown files under content/, and run aphid serve to see it live. The Installation and CLI reference pages have the full setup guide.

Creating a theme with Claude Design

2026-04-26T00:00:00+00:00

The default aphid theme is bare-bones — a white background, the content, and no styling whatsoever. Its main job is end-to-end testing. For the project’s own blog and docs I wanted something that actually looked good, and building it with aphid itself is the best kind of dogfooding.

What I had in mind was a layout that worked for long-form wiki pages and short blog posts alike, with sensible typography, a sidebar for navigation, and syntax-highlighted code blocks that didn’t look like an afterthought. Rather than start from a CSS framework or copy an existing Hugo theme, I used Claude Design as a design collaborator.

What you see here is the result.

Claude Design has plenty of features for steering the direction of a design, but I gave it fairly free rein. The one piece of guidance I did give it was that I like the Catppuccin Mocha palette. Beyond that I let it lead, and iterated on what came back.

Try for yourself

Claude Design is included in all paid plans, though usage on the basic $10 tier is fairly limited. Even there you should be able to push through one or two designs before hitting the cap.

The intended workflow is to set up a design system and feed in a lot of design-related context before you start prompting, but that’s optional. I’ve had good results with very little steering — what you do need to give Claude is a clear picture of the application’s structure and what each template is for. There are more pointers on the AI-Assisted Design wiki page.

Why I built aphid

2026-04-23T00:00:00+00:00

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.

aphid

aphid 0.3.0

Rich wiki categories

Card-based wiki index

Wiki intro page

Upgrading

aphid 0.2.2

AI-agent skills with aphid agent

Home page tag cloud

Tag pages split blog and wiki content

Tag pages no longer paginate

Upgrading

aphid 0.2.1

Wiki-link anchors

Custom heading IDs

Author link field

Social card meta tags

Reading time

Upgrading

aphid 0.2.0

Why

Theme changes — what to update

wiki_page.html gains category

wiki_categories[].name is now a string, never null

backlinks removed from blog_post.html

tags removed from wiki_page.html

wiki_categories removed from blog_post.html and page.html

kind removed from per-page contexts

Universal core: title, url, content, toc, contains_mermaid

Frontmatter changes

New config field

Dev-server quality of life

Author profile images

Upgrading

aphid 0.1.4

Absolute URLs in feeds

Relative image path normalization

Config validation

Better error for non-UTF-8 files

GitHub Action

Upgrading

aphid 0.1.3

Site scaffolding

Content creation

Upgrading

aphid 0.1.2

RSS and Atom feeds

Pagination

Drafts

Also in 0.1.2

Upgrading

aphid 0.1.1

Mermaid diagrams

Markdown alerts

Also in 0.1.1

Upgrading

aphid 0.1.0

What’s in the box

What’s not in 0.1.0

Try it

Creating a theme with Claude Design

Try for yourself

Why I built aphid

Looking for alternatives

Design goals

Tech stack

AI-agent skills with `aphid agent`

Author `link` field

`wiki_page.html` gains `category`

`wiki_categories[].name` is now a string, never null

`backlinks` removed from `blog_post.html`

`tags` removed from `wiki_page.html`

`wiki_categories` removed from `blog_post.html` and `page.html`

`kind` removed from per-page contexts

Universal core: `title`, `url`, `content`, `toc`, `contains_mermaid`