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