Skip to content

2. Documentation Engine: MkDocs and Material

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.

Furthermore, a core tenet of LychD is eXtreme Documentation Driven Development, where the documentation serves as the "Incantation" that the code must fulfill. Eventually, the Agent itself will be tasked with reading, writing, and maintaining its own documentation.

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: MkDocs with Material Theme

A static site generator using Markdown.

  • Pros:
    • Markdown Native: LLMs speak Markdown fluently. This is critical for future Autopoiesis.
    • Material Theme: Providing a polished, modern, and responsive UI out of the box.
    • Extensibility: pymdownx extensions allow for rich content (admonitions, code blocks) without breaking standard Markdown compatibility.
  • Cons: Less "automatic" API documentation generation compared to Sphinx (though mkdocstrings mitigates this). We accept this trade-off for superior narrative capabilities.

Decision Outcome

MkDocs with Material Theme is selected as the engine for The Hexanomicon.

Implementation Details

  • 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/frostmourne.css) overrides the default Material colors to implement the specific purple/cyan/black palette of the Hexanomicon.