Documentation architecture

Where DreamWeave's docs come from and how they reach a browser.

documentation relationship diagram. Its textual ledger or workflow contract is on this page or linked below.
documentation · Mermaid source · Full-size SVG
Read diagram source
flowchart LR
  cargo["Project Cargo source"] --> rustdoc["cargo doc / API docs"]
  rustdoc --> api["Consumer GitHub Pages"]
  metadata["war-room TOML + workflow YAML"] --> rust["Rust war-room generator"]
  rust --> markdown["Generated Markdown + Mermaid"]
  manuals["Hand-authored Markdown"] --> shell["DreamWeave docs shell"]
  markdown --> shell
  template["DreamWeave-Mod-Template"] -.-> shell
  shell --> zola["Zola static output"]
  zola --> pages["StroggForge GitHub Pages"]
  stash["St4sh / Cod3x content"] --> stashshell["Same docs shell in St4sh"]
  stashshell --> stashpages["St4sh Zola / Pages"]
  pages -.->|"links to"| api

Two Kinds of Docs#

API docs and manuals are different animals, and pretending otherwise ends badly.

InputRendered byPublished by
API docsCargo sourcerustdoc, in rustdoc's own UIThe public workflows' docs job on configured main pushes
Manuals and this siteMarkdown plus generated pagesThe DreamWeave docs shell on ZolaThe project's own Pages workflow

This site links to API docs; it does not try to push rustdoc output through Tera. A project with its own Zola site should set publish_docs: false on its Rust workflow, or the two deployments will take turns overwriting each other.

The Mod Template#

DreamWeave-Mod-Template supplies the docs shell: recursive sidebar, breadcrumbs, a local table of contents, drawers for both on narrow screens, scoped styles and no framework. StroggForge imports that shell (the receipt is in site/UPSTREAM.md) and puts its own skin, search and copy buttons on top in separate files, so upstream improvements can still be pulled in.

St4sh and Cod3x#

St4sh is the Lua(u)/OpenMW side of DreamWeave. It publishes mods, their Lua tooling and their docs, and Cod3x, the OpenMW Lua field manual, lives inside it under content/cod3x/docs. It uses the same docs shell. Its site workflow calls StroggForge's createRelease helper and nothing else; no Rust job ever builds, signs or ships it.

When Docs Break#

  • API docs missing: the consumer's docs job, its cargo doc command, Pages permissions.
  • This site wrong: fix the TOML or site/pages and rebuild. Never the generated pages.
  • Layout or navigation broken: the imported shell, site/UPSTREAM.md, then the skin.