I share the same opinion. Its limit make it useful only for a very small set of use cases.

It's being used a lot for code documentation, but MD is bad fit for documentation. Good documentation requires a lot more formatting and cross-referencing than you'd think. Every language I'm using that has been using MD (for embedded and online docs) added extensions, resulting in more fragmentation.

So in general I switch between 3-4 differently-flavoured markdowns constantly. The extended syntax used by various projects sucks. Where did the simplicity of MD go? It reads poorly when unformatted, which is how I read it 99.9% of the time.

I gravitate more towards RST as it's a bit more widely used, but also agree about AsciiDoc.

I agree with both these points. Inter-document references are bad in markdown and wiki style formats. Wikipedia is replete with overlapping and contradictory information that should be pulled from a single source.

Do you have any ideas re link-rot, or underlying assets changing and semantic links becoming invalid? How do you reference a code asset whose name could change, what will not only replace all references in the code but also in the documentation?

Cross-reference checking is a huge problem on it's own, almost unrelated to the formatting being used. Some language tooling do provide cross-ref checking, generally as an extra step part of the documentation generation process. I don't have anything to add to the table compared to what we do already...

For the "more advanced options for true documentation stuff like charts, tables (formatted!), diagrams and more." you might like Obisidian.

But that steers you back towards markdown. How deeply do you not like markdown?

I like Markdown, but I don’t like proprietary Electron apps.