[TuringTest]

There is a fully specified markup language, asciidoc, that reads similar to markdown and provides everything you'd need (as it's equivalent to docbook).

Unfortunately, it's much less known and there is much less software support for it.

[ta988]

That's the reason why I have not used asciidoc, the libraries are either incomplete or inexistant for many languages.

Too bad because I found it superior to markdown for my uses.

[jsdwarf]

The problem with AsciiDoc is that its only maintained implementation AsciiDoctor is written in Ruby, which is a nice server programming language, but not the most logical choice for a multi-platform desktop documentation tool. Sure, there is AsciiDoctorJ, which is a Java wrapper around it, but for PDF generation, UML Diagrams etc you land pretty quickly in Ruby land again, which can get complicated depending on your platform.

[MilStdJunkie]

PlantUML works pretty good in Asciidoc? If you don't want to set up a path to the local jar, you could use Kroki if you don't mind using a service (or you could run Kroki locally).

But I get what you're saying.

There's lots of speedbumps setting up graphing renderers, and the non-Ruby PDF engines aren't optimal (asciidoctor-web-pdf, which is the Paged.JS/CSS PDF toolchain) or they're too arcane for casual users (the DocBook stuff, i.e. DocToolChain/DBXSL/FOPUB). As for the core processor, though, AsciidoctorJS is pacing more or less hand in hand with core Asciidoctor.

Speaking for myself, it was worth the hit, but I'm an edge case. I work primarily with hardware/manufacturing, so I needed the transclusion, conditionals, XML equivalence[1], decent tables, front matter/indices/running content, etc, all in one core spec, because it takes eight months to get a new piece of software. Running back and forth to get permission for every Markdown extension and variant was a non-starter :D

[1] To a nice "relatively sane" XML spec like DocBook