Proposal: Migrate documentation site from Zola to Zensical

[v0lkan]

Context

The current documentation site (https://spike.ist/) is built with Zola, which has served us well: it’s fast, predictable, and low-maintenance.

Over the past months, Zensical has emerged as a strong successor in the static-site/docs space, developed by the authors of Material for MkDocs. It addresses several limitations inherent in older SSG architectures while remaining firmly in the “static, non-JS, non-SPA” category.

This issue proposes evaluating (and likely executing) a one-time migration from Zola to Zensical, with a strong emphasis on correctness, transparency, and reversibility.

Why consider Zensical?

This is not about chasing novelty or consolidating side projects.

The motivation is technical and long-term:

1. Better batteries-included defaults

Zensical provides first-class support for:

• navigation structure
• search
• metadata handling
• documentation-oriented layouts

These are areas where Zola is intentionally minimal and requires more custom glue.

2. Clear lineage and maintenance signal

Zensical is built by the maintainers of Material for MkDocs, a mature and widely adopted documentation ecosystem. This gives higher confidence in:

• long-term maintenance
• documentation quality
• principled evolution (vs. churn)

3. No frontend ecosystem lock-in

Zensical stays firmly out of the React / Node / JS framework ecosystem.

This avoids the maintenance rollercoaster associated with JS-heavy static stacks and keeps the toolchain stable and boring (in a good way).

4. Alignment with future documentation sites

There is value in converging on one static-site toolchain for multiple documentation properties, reducing cognitive overhead and duplicated plumbing over time.

---

Migration feasibility

There is no official Zola → Zensical converter, but this migration is semantic rather than mechanical, which makes it well-suited to a controlled, one-off transition.

Key points:

• Content is already Markdown → portable by design
• Front-matter differences are shallow and mappable
• Templates and navigation can be ported incrementally

LLM-assisted conversion strategy

The proposed approach explicitly uses an LLM as a one-time migration aid, not as a runtime dependency:

• Convert Markdown + front-matter file-by-file

• Translate templates/layouts with human review

• Rebuild navigation explicitly in Zensical

• Use an iterative correction loop:

  • render
  • diff against current site
  • fix deltas surgically

This is:

• a one-off cost
• reviewable via normal diffs
• easy to abort if quality is not acceptable

No ongoing dependency on LLM tooling is introduced.

---

Risk management

To keep risk low:

• URLs and page structure will be preserved (or redirected explicitly)
• SEO metadata will be audited before cutover
• Migration will be staged and tested on a preview deployment
• Zola version remains intact until parity is confirmed

If at any point Zensical proves insufficient, the migration can be paused or abandoned with no long-term impact.

---

Proposed next steps

1. Inventory current Zola features in use (templates, shortcodes, nav)
2. Scaffold a minimal Zensical site
3. Migrate a small representative subset of pages
4. Validate rendering, navigation, and SEO parity
5. Decide whether to complete full migration

---

Summary

This proposal is about reducing long-term maintenance friction, not increasing it.

Zola has been solid, but Zensical offers:

• better defaults for documentation
• a clearer evolution path
• and a toolchain that remains static, predictable, and non-JS

With a carefully scoped, LLM-assisted, one-time migration and a clear rollback path, this is a reasonable and low-risk improvement to the project’s documentation infrastructure.