alt Hacker NewsWe are close to inventing something like deep modules [1] for markdown and a whole methodology of managing docs abstraction and layers. And I'm somewhat serious. It's hard to manage one random, interconnected bag of (spaghetti) markdown. Abstract is the new interface.
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.