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.
| Input | Rendered by | Published by | |
|---|---|---|---|
| API docs | Cargo source | rustdoc, in rustdoc's own UI | The public workflows' docs job on configured main pushes |
| Manuals and this site | Markdown plus generated pages | The DreamWeave docs shell on Zola | The 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
docsjob, itscargo doccommand, Pages permissions. - This site wrong: fix the TOML or
site/pagesand rebuild. Never the generated pages. - Layout or navigation broken: the imported shell,
site/UPSTREAM.md, then the skin.