Skip to content

2. Documentation Engine: Zensical

Context and Problem Statement

LychD is a complex system combining ancient lore with modern engineering. The documentation must be as immersive as it is technical.

Initially, MkDocs with the Material theme was chosen. However, due to ecosystem instability and leadership challenges in the MkDocs project, the decision was made to migrate to Zensical, the high-performance successor developed by the Material for MkDocs team.

Furthermore, a core tenet of LychD is eXtreme Documentation Driven Development, where the documentation serves as the "Incantation" that the code must fulfill. The doctrine also leaves room for later stages in which the Agent reads, writes, and maintains documentation as part of the same disciplined loop.

Requirements

  • Simplicity & Isolation: A mechanism is required that isolates content from presentation, remaining syntactically simple enough for AI agents to generate reliably.
  • AI Compatibility: The syntax must be Markdown-native and intuitive, minimizing hallucinations or syntax errors when generated by LLMs.
  • Aesthetic Flexibility: The tool must support deep customization via CSS overrides to achieve the "Grimoire" visual identity.
  • Developer Experience: The tool must provide instant local previews and seamless deployment to GitHub Pages.
  • Accessibility: The output must be natively mobile-friendly and accessible.

Considered Options

Option 1: Sphinx (reStructuredText)

The traditional standard for Python projects.

  • Pros: Powerful directives, deep Python API documentation support.
  • Cons: rST syntax is notoriously brittle and confusing for both humans and LLMs. The default themes are dated. Customizing the visual style requires significant effort.

Option 2: Wiki (GitHub/Confluence)

Standard hosting provided wikis.

  • Pros: Zero setup.
  • Cons: No version control alongside code. Hard to theme.

Option 3: Zensical

A modern, high-performance static site generator designed as the successor to MkDocs/Material.

  • Pros:
    • Successor Doctrine: Built by the Material for MkDocs team to address the long-term sustainability of the ecosystem.
    • Rust Core: Extreme build speeds and scalability.
    • Native Material support: Built-in high-fidelity theme features.
    • Markdown Native: Maintains the Autopoiesis compatibility.
  • Cons: Younger ecosystem compared to MkDocs, but backed by the same core maintainers.

Decision Outcome

Zensical is selected as the engine for The Hexanomicon.

Implementation Details

  • Engine: zensical (replacing mkdocs).
  • Configuration: Managed via zensical.toml.
  • Theme: material (Scheme: Slate/Dark Mode) to match the "Lich" aesthetic.
  • Structure: Documentation lives in docs/ and is deployed to GitHub Pages.
  • Extensions: Enable admonition, pymdownx.details, and pymdownx.superfences to allow for "Grimoire-style" warnings and collapsed sections (e.g., "Forbidden Knowledge").
  • CSS: A custom stylesheet (stylesheets/hexanomicon.css) overrides the default Material colors to implement the specific purple/cyan/black palette of the Hexanomicon.

The Layered Grimoire Strategy

A delicate balance between narrative depth and engineering clarity is maintained by splitting the documentation into three distinct tiers:

  • The Iron Covenants (ADRs): docs/adr/ remains strictly technical and objective. The dark fantasy vocabulary (Vessel, Phylactery, Thrall) is used solely to reduce cognitive load and map domains. It is the architectural ground truth.
  • The Outer Wall (The Grimoire): All general documentation within docs/. These pages carry the dark fantasy aesthetic, but remain functional guides for operating the software.
  • The Inner Sanctum (Lore & Transcendence): Specifically docs/divination/transcendence/. This is where the project explores esoteric philosophy, Vedic metaphysics, and restrained mythic metaphor — the "why" behind the "how." The lore is optional. It does not help configure the system; it rewards the dedicated practitioner who wants to understand the ultimate intent without confusing the casual contributor seeking an API endpoint.

Agent Scope Boundary

Agent routing is not documentation canon. LychD may track thin scope cards in .agents/scopes/** to tell coding agents when to load a bounded context, which docs/source files to inspect, which files they may edit, and how to verify the work. These files are agent choreography, not Zensical content.

If a scope starts explaining project truth, that truth belongs in docs/**, an ADR, or source contracts. The scope should remain a map that points to canon, not a parallel grimoire.

Consequences

Positive

  • Cultivation of Lore: The separation allows the project to maintain its stylized "Grimoire" aesthetic and mythic philosophy without compromising the perceived professionalism of the engineering architecture.
  • Engine Performance: Zensical's Rust core drastically reduces build times, improving the developer experience.

Negative

  • Ecosystem Immaturity: Zensical is newer than MkDocs, which may lead to missing plugins or edge-case bugs that require upstream fixes.