aphid 0.2.2

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.

Home page tag cloud

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:

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:

1. Replace the posts loop with two guarded sections for blog_posts and wiki_pages.
2. 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.

See also: AI-Assisted Writing, AI-Assisted Design, Themes > home-html, Themes > tag-html.