[TheRealPomax]

You get links, if you need more than that you're probably overcomplicating your documentation. Transclusion might sound nice, but now your docs have depedencies and they become harder to send, harder to host, and harder to edit (is this edit in this transcluded file going to work for every other file that includes it?). Then someone goes "I use it for templating" and now you have a CMS. It's a slippery slop that markdown sidesteps by going "no. You get links. If you need more than links, you're probably overcomplicating your documentation".

[fhennig]

I find this view a bit simplistic. As a reader I find it much easier to follow if I don't have to piece information together from different documents. Including relevant sections in the correct place will improve the flow of the text a lot.

I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter.

I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).

[TheRealPomax]

That, honestly, feels like a problem with the markdown reader, not the format itself. A problem common to modern browsers, but also prevalent in many doc readers: Much like how a good code editor can show you "the thing you need to resolve" inline (e.g. looking up the definition of a function you highlighted), a good markdown reader should be able to trigger what looks like a transclusion in the document you're reading when you click a link, in addition to the normal link resolution.