Waiting for input...
Star SPIKE on GitHub

ADR-0020: Switch to Zola for Documentation System


Context

While Docsify has served our documentation needs, we’ve identified several limitations: *

  • SEO capabilities are limited due to client-side rendering
  • Performance is dependent on JavaScript execution
  • Template customization options are restricted
  • Page load times can be impacted by the single JavaScript parser

We need a documentation system that addresses these limitations while maintaining the benefits of our current system.

Decision

We will switch to Zola as our documentation system, replacing Docsify.

Rationale

Zola offers several advantages that align better with our current needs:

  • Static site generation provides better SEO capabilities
  • No JavaScript dependency for core functionality
  • Flexible templating system using Tera
  • Fast build times due to being written in Rust
  • Direct rendering to HTML improves page load performance
  • Maintains support for Markdown-based content
  • Built-in syntax highlighting and search capabilities

Consequences

Positive

  • Improved SEO through static HTML generation
  • Better performance due to pre-rendered content
  • More flexible templating and customization options
  • No JavaScript requirement for core functionality
  • Faster page loads
  • Maintains Git-based workflow
  • Syntax highlighting out of the box
  • Built-in search functionality
  • Clear separation between content and presentation

Negative

  • Requires a build step (though builds are very fast)
  • Team needs to learn Zola-specific templating syntax
  • Migration effort required for existing documentation
  • Need to set up build pipeline for documentation deployment

References