Although it's already on your roadmap, but it definitely needs more complex examples. Fiddled around a bit with links to same-doc references. Got it to work, but took a while.
AsciiDoc is much nicer, but has the unfortunate flaw of having basically one implementation and it's in Ruby (the JS one is just transpiled, the Java one runs on JRuby, not sure about Go and Haskell).
They don't even have a Python library, which basically guarantees that AsciiDoc won't be taught in colleges.
I like AsciiDoc, but not nearly enough to mess around with installing Ruby and Gems and then having to do the same for anyone else at work that needs to build the docs for whatever reason.
Ruby is basically a non-starter for me in general. Dependency management and interpreter versioning is a pain in the ass for interpreted languages, so I'd rather have as few as possible on my system. I've already got Perl and Python installed by default, I'd rather not add a third.
I'm still upset that Markdown ended up getting all the mindshare and doesn’t evolve. All the fragmentation through different markdown flavors doesn’t help.
Although it's already on your roadmap, but it definitely needs more complex examples. Fiddled around a bit with links to same-doc references. Got it to work, but took a while.