Spokes.wiki Search About

Synthesis

The evolving thesis for the static-site / Jamstack spoke. Updated on every ingest.

Current thesis

The web's publishing substrate is shifting from request-time, database-backed CMS (the wordpress model) toward build-time pre-rendering (static-site-generator

Two distinct "fast"s. Don't conflate them: eleventy wins build speed (~12× faster than Astro on 4k files); astro wins runtime experience (66–67% Core Web Vitals pass rate). A team chooses on which axis hurts more. The build-speed axis now has a Rust entrant: zola, a single-binary engine (Tera templates, batteries-included Sass/search/ images) that claims sub-second whole-site builds — the direct counterpart to hugo (Go single binary), reinforcing that "no Node toolchain + one executable" is its own coherent design lane. Astro narrows the build gap (2026-06-22). Astro 7.0 rewrites the .astro compiler Go → Rust and adopts Vite 8 / Rolldown for 15–61% faster builds — Astro reaching for the same Rust-speed lever as zola/hugo rather than ceding build speed. The "two distinct fasts" split persists but shrinks: runtime was never Astro's problem, and the build axis is no longer a clean win for the single-binary camp.

A documentation-SSG sub-genre is now legible. Three docs-first generators span the major language ecosystems — docusaurus (React), vitepress (Vue, Vite-powered, the VuePress 1 successor), mkdocs (Python, single-YAML config, Material theme) — all converging on the same shape: Markdown content + a default doc theme → static HTML, differing mainly in runtime stack (and whether they hydrate into an SPA, as VitePress/Docusaurus do, vs. stay near-zero-JS). That convergence is itself evidence on the open question below: even as the frameworks differ, the SSG form factor is stable.

Astro leads its weight class, not the field. Independent CrUX data (core-web-vitals-wordpress-astro) puts Astro 4th of 7 — behind hosted site builders (Duda 85%, Wix 80%, Shopify 79%) but ahead of every self-hosted CMS (Drupal, Joomla, wordpress last at 49%). So the win is "best among open developer frameworks," and the wordpress performance gap is real and third-party-confirmed.

It's a whole pipeline, not just a generator swap. The displacement of the monolithic CMS has two more layers beyond the SSG itself. netlify — which coined "Jamstack" (founded 2014, runs Jamstack Conf) — is the deployment substrate: git push → build the SSG → serve generated files from a global CDN, with deploy previews and serverless/edge functions filling the dynamic gaps a pre-rendered site can't (vercel in ../cloud-wiki is the React/Next-leaning sibling; Netlify is framework-agnostic). headless-cms is the content-management half — a back-end-only content repository exposed over an API (REST/GraphQL), decoupling content from presentation, the direct answer to "drop WordPress, and where does editable content live?" (git-based variants like Decap commit Markdown to the repo; SaaS variants like Contentful/Sanity serve via API). The pipeline — headless content → SSG build → Netlify CDN — has each layer doing one job the wordpress monolith did all at once.

The content layer gets its first named subject — and a third hosting position. strapi is the first concrete headless-cms product paged here, and it doesn't sit cleanly in the SaaS-vs-git split: it's API-based (DB-backed, REST/GraphQL) like Contentful/Sanity, yet self-hosted and open-source like the git-based tools — you run the server and own the data, but content lives in a relational DB, not version-controlled files. That makes it the closest structural analogue to wordpress in the headless world (same open-source, self-host-and-own posture; opposite, decoupled architecture) — evidence that "drop WordPress" need not mean "rent your content from a vendor." The own-your-stack axis and the own-your-plain-files axis are separable, and Strapi takes the first without the second.

The displacement also needs a turnkey-template layer — and it's filling in. One thing the wordpress monolith always had that bare SSGs didn't: pick-a-theme-and-go, a non-developer's path to a finished site. astro-themes is that layer arriving for the SSG world — Astro's official gallery of ~900 community-submitted ready-made sites (free and paid) across the same use cases WordPress themes cover (blog, portfolio, e-commerce, SaaS, docs, education). It runs on the same open-submission model as the awesome-static-generators / jamstack-generators-list catalogs, but applied to finished sites rather than tools. So displacement is not only the per-layer pipeline above (content / build / delivery) but also ecosystem maturity: the SSG side growing the turnkey-site economy that made WordPress the default. (Vendor-self-reported count, volatile listing — an adoption signal, not a benchmark.)

The static-first core now extends into the dynamic. astro-server-islands (server:defer) is the server-side complement to islands-architecture: ship a build-time static, CDN-cacheable shell immediately, then fetch only personalized fragments on demand as HTML, with little to no client JS. That dissolves the old SSG bargain ("pre-render everything, but then personalization can't fit") without becoming a full SSR meta-framework — Astro now spans static shell → server islands (no-JS dynamic) → client islands (hydrated), a finer spectrum than the static/SSR binary, and evidence on the SSG-vs-meta-framework question that the static-first core extends into per-request rendering rather than abandoning build-time. (Caveat: server islands need a runtime/adapter, not pure static hosting.)

Open questions

The extension is not a superset, and it has no spec (2026-09-02)

mdx was hunted to close half of the content-pipeline edge and returned something better than the source asked for: there is no MDX specification. No spec page (both plausible URLs 404), no grammar or spec document in mdx-js/mdx, no conformance corpus. The format is defined by its reference compiler, which is precisely the position Markdown was in before CommonMark — six companies writing a grammar and 652 test examples because one buggy implementation had become the definition. The fix did not propagate upward: the extension built on top of the specified format is itself unspecified.

Half of it is specified by inheritance, and the seam is where the interest is. @mdx-js/mdx parses prose through remark-parse → micromark, which claims "100% to CommonMark" and passes ~650 CommonMark tests, so MDX's markdown layer is conformant and its JSX layer is whatever acorn and the compiler do. One format, two halves, one of them tested.

And MDX is not a superset of Markdown, which matters directly to the generators paged here. It removes indented code blocks (indentation is reserved for component nesting), autolinks, HTML syntax and HTML comments, and requires escaping bare < and {. Every generator in this spoke that presents MDX as the richer option is presenting a format that silently drops CommonMark features a .md file may already be using. Nothing in the corpus had said that; MDX is discussed here as an addition (docusaurus, astro-7) and the subtraction was invisible.

The autolink case is the one to keep. CommonMark spends 90 of 652 examples on links, its second-largest section, because that is where implementations diverged. MDX deletes autolinks at exactly that spot, because <svg:rect> now has to be JSX. The place the base spec worked hardest is the place the extension could not keep — which is a general shape worth watching as more flavours arrive, not a one-off.

The roster's gap was a user, not a language (2026-09-02)

Growth edge 7 named Pelican, Bridgetown, Hexo and Publii as "generators outside the JS/Go/Rust roster," and hunting all four says the edge had diagnosed itself wrongly in three separate ways.

It was not about recency. Pelican is from 2010 and Hexo from 2012 — older than every generator paged here except Jekyll. The corpus had not been tracking a newer wave; it had been tracking a language.

It was not about obscurity. Hexo has 41,768 stars, more than Astro, Hugo or Jekyll, and had never appeared in this spoke. The roster's shape was a property of how sources arrive, not of what is used.

And the real gap was who is at the keyboard. Publii is a desktop application with a graphical interface — install it, write, press publish, no terminal at any point. Every other generator in this corpus is a CLI, and that assumption was invisible because nothing had broken it. It matters most where this spoke already has a live thread: wordpress-market-share-decline and headless-cms describe people leaving WordPress, and WordPress's users are overwhelmingly not command-line users. Publii is the first tool paged here built for the person actually doing the leaving, and it names the thing it removes in WordPress's own terms — "without a database, PHP, or a public admin panel." Pelican's WordPress importer is the other half: the first mechanism for that migration in the corpus rather than another report of the trend.

A second finding, on the spoke's own boundary. Bridgetown ships the Roda web framework and advertises PostgreSQL, asking on its front page "Static Sites? Fullstack Applications? Both?" — which is precisely the move that put Next.js, Remix and Gatsby out of scope here in June. Every out-of-scope example in the corpus is a React framework, so the exclusion has read as a JavaScript phenomenon. It is not. A Jekyll descendant in Ruby accumulated a server too. The pressure is on the genre, not on one ecosystem, and the line this spoke drew is about what a tool is for rather than what it is written in.

Two smaller observations. Copyleft is over-represented outside the roster: Pelican is AGPL-3.0 and Publii GPL-3.0, against the MIT/Apache monoculture of everything paged before, and nothing fetched says what either licence means for a commercial site built with them. And Hexo's fork count is 39 — against 41,768 stars, with network_count agreeing — where the other three sit between 7:1 and 16:1 stars per fork. No explanation was found and none is offered; it is recorded because fork counts are one of the few contribution proxies used here, and this is the clearest case of one not meaning what it usually does.

The scoreboard is undefined for most of the genre (2026-09-02)

Hunted at the curator's request: how do you improve Core Web Vitals on Eleventy? The answer came back in two parts and neither is a technique.

Eleventy's own performance documentation never mentions the metrics. Not Core Web Vitals, not LCP, CLS or INP (eleventy-performance-docs). "Performance" on that page means build performance, and every one of its eight recommendations is about making builds faster. The one runtime sentence is a statement about a default — "by-default we do not include any costly runtime JavaScript bundles that often hamper site performance" — and the Image plugin, which adds width and height "to reduce layout shift" and emits AVIF with srcset, documents that work under its build cost. So the biggest LCP and CLS levers this generator has are shipped as defaults, and the project has nothing to instruct. That is a real answer to the question, and it is why no first-party guide exists to find.

The community measures it anyway, and the measurement has a hole. speedlify runs Lighthouse weekly against 1,145 Eleventy sites and reports a median performance score of 98, with 150 sites scoring 100 across all four categories. That is the strongest number this spoke has ever held for the pre-rendered-is-fast argument. And only 118 of those 1,145 sites have CrUX field data — about one in ten.

That gap is the finding, and it is about this spoke's own scoreboard rather than about Eleventy. core-web-vitals ranks platforms by field pass rate: Astro 66–67%, WordPress 48–49%, Duda 85%, Shopify 79%. Those are CrUX numbers, and CrUX only reports a site once it has enough real traffic to be statistically usable. Eleventy cannot be placed on that list — not because it performs badly but because nine in ten of its community sites are too small to be measured at all. A median Lighthouse of 98 is a lab result on a simulated device and is not the same quantity.

So the platform scoreboard is only defined for platforms whose sites are big enough to appear in CrUX, and that systematically excludes personal sites, documentation and blogs — the small-site end of the genre where Eleventy, Jekyll, Zola and now Pelican and Publii live, and precisely the case the static-generation argument is usually made about. The scoreboard is not neutral about site size, and the corpus had been reading it as though it were. It remains the right comparison for WordPress against Astro; it cannot answer "is Eleventy fast in the field," and no source here can.

This also sharpens the page-weight-is-not-destiny tension rather than resolving it: that entry already showed the field ranking disagreeing with lab scores and byte counts. Now the corpus has a case where the field number does not exist at all.

Two ways to ship search, and only one of them publishes a number (2026-09-02)

Hunted at the curator's request. Zola's built-in search turns out to be the missing second point on an axis Pagefind had to itself.

Zola generates a search index in four formats — elasticlunr JavaScript or JSON, fuse JavaScript or JSON — and then stops, explicitly: "Zola makes no assumptions about your search function and doesn't provide the JavaScript/CSS code to do an actual search and display results." Pagefind does the reverse, shipping a chunked index and a UI component, on the argument that "searching in the browser only ever needs to load a small subset of the search index."

So the axis is how much of the search the tool owns, and both ends are now paged. What the corpus cannot yet do is price the difference. Pagefind's design is measured — 2,585 pages, 153 chunks, ~170 KB for a cold first search against a ~10 MB total index — and Zola's documentation gives no size figure of any kind for a feature built into a binary whose headline is "blazing fast." The chunking argument is still an assertion with one worked example and no counter-example, which is what growth edge 5 now asks for.

A smaller pattern, visible only after a day of hunting. Four of the six generators paged or re-read in the last two days are not permissively licensed — Pelican AGPL-3.0, Publii GPL-3.0, Zola EUPL-1.2, against MIT for Hexo and Bridgetown. The MIT/Apache monoculture the corpus appeared to show was a property of which generators had been paged, not of the genre. Nothing fetched says what any of these licences means for a commercial site built with the tool, and that is a gap rather than an observation.

And three of today's subjects are still 0.x: Zola at v0.23.4 after ten years, Publii at v0.47.x after eight, CommonMark at 0.31.2 after twelve. Long-lived, widely deployed, and none of them willing to call itself finished. Recorded as a pattern to watch; the corpus has no source on what a 0.x version number is being used to communicate.

Growth edges

Ranked; each names the kind of source that would close it (see ../QUALITY.md → Growth edges).

  1. Is "SSG" still a coherent category? astro-7 pushes the spoke's central subject onto the web-framework side from inside, and the boundary this spoke scoped around keeps eroding. — needs: a T1/T2 source treating the SSG-versus-meta-framework line directly rather than by implication. Promoted 2026-10-07 to the hub ## Most wanted (#54) — the edge-queue blind-spot pick for this quality cycle: the spoke had a well-developed edge but zero hub-level visibility, so the Research Pass had never once drawn a candidate from it.
  2. What build-time actually buys, measured. The category coheres on build-time HTML and splits on how much client JS rides along; nothing here measures the difference in delivered cost. — needs: a T2 comparison across the hydration edge (cross-links ../webperf-wiki).
  3. The WordPress decline, sourced past headline share. — needs: T1/T2 survey data rather than a market-share snapshot.

Coverage edges (added 2026-08-08, at the curator's request for a wider backlog). These widen what the spoke covers instead of answering an open question above; one ordinary solid source closes any.

  1. Where the output is actually served. netlify is the only host with a page, while GitHub Pages, Cloudflare Pages and Vercel carry most static sites. — needs: first-party docs and limits per host (T3 fine, vendor facts). Cross-spoke: pricing belongs to ../cloud-wiki.
  2. Search, the feature build-time HTML cannot give you. Pagefind, Lunr and hosted Algolia are the standard answers and none is written up — closed for Pagefind, 2026-09-01, with both halves the edge asked for: the project's own docs and an implementation report measured from this wiki's own build (pagefind — 2,585 pages, 153 index chunks at a 31 KB median, one ~2 KB fragment per page, ~170 KB for a cold first search). — still needs: the alternatives, since one instance is not a comparison. Lunr's whole-index model is the thing chunking exists to avoid, and hosted Algolia is the answer that reintroduces the server this whole spoke exists to remove. Either would turn a description into a trade-off. T2/T3. Advanced 2026-09-02 by a Zola re-read: zola ships an index and no search UI — four formats for elasticlunr, fuse.js and tinysearch — and says outright that it "makes no assumptions about your search function." That is the opposite trade from pagefind (chunked index plus a UI component), so the spoke now has both ends of the ship-it-for-you axis. What it still does not have is the number: Zola's docs state no index size, no page-count guidance and no growth warning, and whether an elasticlunr or fuse index must load whole is unestablished here. — needs now: a measured index size for a Lunr-family search at a comparable page count, the one figure that would make the Pagefind chunking argument testable rather than asserted.
  3. The content pipeline itself. Markdown flavours, MDX, frontmatter conventions and Astro's content collections are the layer authors touch daily; the spoke covers generators and skips their input format. — needs: the CommonMark or MDX specification plus one generator's content docs. Half closed 2026-09-02, cross-wiki. The CommonMark specification was routed to ../dev-tooling-wiki, which owns format specs and their reference implementations (dev-tooling-wiki/commonmark — v0.31.2, 652 conformance examples, 20% of them on emphasis alone). That is the base grammar every generator here parses, and it is linked rather than duplicated. — needs now: the flavour layer this spoke actually touches — GFM's extensions (tables, task lists, autolinks), MDX, and one generator's content-collection docs. A base spec does not tell you what Docusaurus or Astro add on top, and the additions are what authors hit. MDX hunted and paged the same day at the curator's request (mdx, T1) — and the hunt's result was that there is no MDX specification to fetch: no spec page, no grammar in the repo, no conformance suite, the format defined by @mdx-js/mdx alone. — needs now, narrowed twice: GFM's extension set (tables, task lists, strikethrough, autolinks — the flavour every generator here actually ships) and one generator's content-collection docs.
  4. Generators outside the JS/Go/Rust roster. CLOSED 2026-09-02 (hunted at the curator's request): pelican, bridgetown, hexo and publii, one T1 page each from project documentation and the GitHub API. The edge was written as a language gap and it was not one — see the section below. Successor: the roster is still every-tool-is-a-CLI apart from publii, and nothing here describes what a non-technical author's workflow costs in practice. — needs: a second GUI-first or hosted-editor generator, or one account of a real WordPress-to- static migration by someone who does not use a terminal.
  5. A field measurement of the small-site end. speedlify gives 1,145 Eleventy sites a median lab score of 98 and only 118 of them have CrUX field data, so the platform scoreboard on core-web-vitals simply has no entry for Eleventy, Jekyll or Zola — not a bad one, none. — needs: RUM or CrUX-origin data covering low-traffic static sites, or one generator's own field study. Failing that, an explicit statement of what the lab/field gap is worth would let the corpus stop treating a Lighthouse median and a CrUX pass rate as comparable. Narrowed 2026-09-02 by a hunt into CrUX itself (../webperf-wiki: webperf-wiki/crux). Google's methodology says the popularity threshold "has been chosen to ensure that we have enough samples to be confident in the statistical distributions" — so the exclusion is statistical, not editorial, and no amount of effort gets a low-traffic site into CrUX. This edge can therefore never be closed with CrUX data; it needs first-party RUM. Google also does not publish how many origins CrUX covers. — needs now: a static-site host or generator publishing aggregate web-vitals-library RUM across its users' sites.

The one feature that needs a server, and the shape of doing without (2026-09-01)

pagefind is the first source here on the thing a static site cannot do by construction. Search needs an index and something to query it, and a site made of files has neither. The three standard answers each pay somewhere: hosted search (Algolia) puts the server back, whole-index client search (Lunr) makes the reader download the corpus, and Pagefind splits the index into chunks so the browser fetches a small subset — a metadata file, one or more index chunks, and a small fragment per result, with a Rust indexer producing them after the build and a WASM module reading them.

The claim is stated as a budget rather than as speed: "full-text search on a 10,000 page site with a total network payload under 300kB, including the Pagefind library itself." Measured on this wiki's own 2,585-page build, a cold first search is on the order of 170 KB — library, WASM, metadata and one chunk — against a full index of about 10 MB that nobody ever downloads. The shape holds at a quarter of the quoted scale, from artifact sizes rather than a network capture.

This sharpens the spoke's competing definitions of "performance." eleventy sells build speed; astro sells runtime core-web-vitals; Pagefind sells neither and instead names a payload ceiling for a feature, which is the ../webperf-wiki frame (performance-budget) arriving inside a static-site tool. Three tools, three units — seconds, vitals, kilobytes — and a reader comparing them on "fast" is comparing nothing.

The cost the docs do not state is at the deploy end, not the reader's. Pagefind names every artifact by a content hash and prunes nothing, so a build directory accumulates dead chunks across incremental builds: 1,191 index chunks of which 152 live, after two days on this corpus, and 6,654 files / 132 MB against 5,378 / 95 MB for a cold rebuild of identical content. And the artifact count is the operative number, not the byte count — 2,589 fragments averaging 2,149 bytes occupy 12 MB on disk at a 4 KB block size, and publish time scales with objects rather than bytes. A spoke about build-time output should hold that: the reader's bandwidth and the publisher's file count are different budgets, and this design trades one for the other.

Contradictions / tensions

Cross-wiki adjacency

This spoke borders the sibling ../webperf-wiki (page-weight minimalism, byte budgets) at exactly core-web-vitals and the zero-JS ethos. They're kept separate: webperf is about measuring and minimizing bytes; this spoke is about the tools and the publishing-platform landscape. Logged as the runner-up at routing time (see ../log.md). Note the live disagreement above: our source says bytes aren't destiny, which is in direct tension with ../webperf-wiki's core premise — a good question to put to both wikis.

Index

Catalog of every page, grouped by schema.org @type. Read this first when answering a query, then drill into the relevant pages. Updated on every ingest.

NewsArticle (sources)

WebPage / ItemList (sources)

SoftwareApplication

TechArticle (sources)

DefinedTerm

Organization / Platform

Synthesis

Related pages

Links to

Linked from