Why Aardvark rebuilds every page (for now)

The edit loop stays fast by skipping the heavy publish phases — and per-page incremental skipping is a harder promise than it looks.

Here’s an honest engineering answer to a question we get: does vark do incremental builds? Today, no — every build renders every page. The edit loop stays fast a different way: vark dev skips the build’s heaviest phases entirely (Open Graph card rendering and the whole-site PDF, which only matter when you publish), and the render pipeline itself is lean enough that a full re-render of a mid-sized site lands in seconds.

Why not skip unchanged pages? Because on a docs site, “unchanged” means much more than “the Markdown file has the same bytes.”

A rendered Aardvark page is a function of many inputs. The obvious one is the page’s own source — prose, front matter, the `` tags inside it. But pages also read shared inputs: the site config (a renamed tab changes every page’s header), the theme (one SCSS variable recolors the whole site), data files loaded through templating, snippets and includes, and the navigation itself — adding one page inserts a sidebar entry on all of its siblings. Skip a page whose own file is unchanged while one of those shared inputs moved, and you ship a stale build that looks fine until someone notices the sidebar is missing an entry.

So any future page cache has to be conservative: a page can only be skipped when everything that could affect its output is accounted for, and anything site-wide must invalidate broadly rather than cleverly. That’s a deliberate trade. A cache that is occasionally too eager to rebuild costs you seconds; a cache that is ever too eager to skip costs you correctness, and a docs generator that sometimes publishes stale pages is worse than a slow one. Until we can make the skip provably safe, rebuilding everything — and keeping “everything” cheap — is the honest default.

What is cached, then

Plenty — just not the page HTML. The expensive work that can be keyed honestly is:

• The island prerender. Since 0.3.3 each page’s baked island markup is stored under .aardvark-cache/prerender/ under a content key covering the page’s HTML, both JS bundles, your lockfile and install-state markers, the Aardvark version, the Node binary and a short list of environment variables. A page whose HTML didn’t move reuses its bake byte-for-byte, and a page holding no island never reaches Node at all. Two gaps the key can’t see: an island that renders from the clock or process.env, and a linked package edited in place.
• Everything fetched or highlighted at build time — repo-browser archives, their Markdown previews and highlighted source — so a rebuild doesn’t re-download or re-render what it already has.
• The whole-site PDF, which a site can republish for pdf.reuseForDays instead of re-rendering every page into it.

Which is the shape of the honest answer: cache the parts whose inputs you can enumerate, re-render the part whose inputs you can’t. If you want the fastest possible loop while authoring, vark dev --no-ssr drops island prerendering too — at the cost of dev pages no longer matching what vark build publishes, so verify with a real build before you ship.

The dev-loop details live in the dev command docs, and the changelog has the release notes.