Docs Phase 6: Integrate generated API docs with Docusaurus

[MichaelFisher1997]

Parent: #609

Summary

Integrate generated API documentation output with the Docusaurus/docs site once the generator output format is stable.

Areas To Resolve

• MDX frontmatter shape.
• Sidebar/autogenerated sidebar behavior.
• Zig syntax highlighting support.
• Cross-links between modules and declarations.
• Escaping generated code/signatures so MDX does not break.
• Asset/link policy for diagrams or external references.

Acceptance Criteria

• Generated docs can be consumed by the docs site without manual edits.
• Sidebar behavior is predictable.
• Code blocks and signatures render correctly.
• Integration contract is documented for future generator changes.

[github-actions]

This is a Feature Request that appears premature — the prerequisite components don't exist yet.

Analysis:

• No Docusaurus site exists in the codebase (no docs/ website, no Docusaurus config)
• No API doc generator exists (no zig doc integration, no doctest/apidoc tooling)
• The issue references parent Docs: Build a maintainable generated API documentation pipeline #609 (which isn't available here) and assumes "generator output format" is being stabilized — but no generator is present

Recommendation:

This should be broken into at minimum two separate tracking issues:

1. Set up Docusaurus site — bootstrap the docs site first
2. Build API doc generator — produce machine-readable docs output (e.g., JSON from zig doc)

Once both exist, the integration work (MDX frontmatter, sidebar, syntax highlighting, cross-links, escaping) becomes concrete and testable.

The acceptance criteria ("generated docs can be consumed without manual edits") also can't be validated until the generator itself is implemented.

Commenting on the issue now.

opencode session  |  github run