I had many years experience with various (mainly software) documentation formats, including Plain Old Documentation (POD), reStructured Text (reST) + Sphinx, DocBook, AsciiDoc, Vimwiki, LaTeX, mdoc, troff and of course HTML. But only GNU Texinfo and its corresponding Info format is my choice for documentation and static websites generation. Previously I used reST everywhere, but since then I know many of its disadvantages and limitations (like available, but rather bad export to Texinfo/Info and TeX).
Remark about Markdown format (MD): there is no such format, stop suggesting it! There are only many vaguely incompatible dialects and implementations. You can always be sure that your .md won’t work with another implementation. Only very tiny subset of features are guaranteed to work reliably. I heard about CommonMark (CM), but do not see its widespread usage at all.
I will overview the source format (that is intended to by writeable) and target format (readable one). There will be neither Vimwiki nor Org-mode, because they are editor-locked, however both of them could be perfect candidates in most cases too.
What do I want from source format? Easiness, convenience, rich features, machine friendliness and HTML output at least.
What do I expect from target format? Ability to read it in terminal (PDF
looses). Internal links (man and POD loose). man and HTML are viewable
only with specialized software. Built-in indexing/searching ability
exists only in GNU Info (however you can use external software like