We 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.

1. https://softengbook.org/articles/deep-modules

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.