ReStructuredText (.rst, what Sphinx uses) handles it quite well. I understand why Markdown became so popular (super easy/intuitive) but what I don't understand is why so many documentation systems use it. It's quite limited... On purpose!

You want to support simple text features in a forum or comments on a website? Markdown is perfect. You want to support basically every documentation feature imaginable while still retaining reasonable ease-of-use? ReStructuredText is the way to go.

As I understand it, rST and Asciidoc are roughly equivalent in that they provide significant document-oriented upgrades to Markdown - upgrades that are on the order of Docbook. This makes them attractive. But you won't convince me that cross-document deep linking is a solved problem unless you accept that the use case is a static document base. Anything to do with products under continuing development is going to bring headaches. Is there any CMS that "solves" this in a robust way ? I wonder.

It's fairly easy in rST. I just can never remember the syntax :P

We switched the iommi docs from markdown to rST for this and many other similar issues of rST being more powerful.

Not hard with RST/Sphinx, but that comes with other usability nits.

nah we use asciidoc for this. worked next to the guy who invented it back in the day. another team at our company used to to make topic-based authoring the CMS standard. been doing this fine for years now and even the writers seem happy (super rare for tech writers innit)