Markdown is a great format for writing basic HTML documents. It sucks for writing books or complex documents, as Matthew Butterick has argued [0]. But that's only a problem if you try to write books or complex documents in Markdown.
[0]: https://docs.racket-lang.org/pollen/second-tutorial.html
The rust official docs are also written in markdown and thrown at mdbook (https://rust-lang.github.io/mdBook/) to generate documentation of a similar style, but it's much more book like.
I am pretty much all in for markdown based documentation for almost everything. It does what I need and nothing more.
If I need more control over styling, that's a different story, but thankfully almost all my use cases are good enough without such control.
It's a pain in the ass to use, and I wish more people would focus on concise and easily referenced/searched/indexed material in markdown rather than novels written in TeX.
For example, Agner Fog's writings are fantastic content, and awful to navigate. The Rust Programming Language does exist in book form, but I find myself referencing it constantly as a technical manual and it would suck to do that if weren't structured the way it is using mdbook.
For the love of all that is sacred, please stop writing technical manuals like I'm going to ever going to read the whole thing. Every piece of information should be short, fit entirely in a reasonably sized browser window, be indexed for search, and if it lends itself to cross-referencing it should be filled with links to itself.
That's the kind of thing that markdown and site generators using markdown excel at.