Comment by aDyslecticCrow

Docs is already a notoriously under-prioritized and often rotting part of software projects. Making it more complex and larger to maintain and update doesn't feel like the right solution.

Nested markdown or restructured-text or asciidoc is pretty good workflow already to re-use blocks, link to different pages, or do some rich formatting like collapsible sections.