[Issue 16112] Enhance ddoc with more markdown support

[via Digitalmars-d-bugs]

https://issues.dlang.org/show_bug.cgi?id=16112

--- Comment #8 from greensunny12 at gmail.com ---
> although I'm not speaking out of experience. Everyone interested in more MarkDown can use that instead of pure DDoc today and gather some intel. Maybe even those not interested in it, to see if it would break anything for them.

tl:dr: imho in the best case this will lead to a fragmentation as once you
start using the full set of Markdown in your documentation, you can't switch
back.

Full text:
----------

I can speak out of experience as we tried _all_ available solutions for Mir,
here's a selection of the top five:

- ddox  (https://github.com/libmir/mir/pull/150)
- bootDoc (https://github.com/libmir/mir/pull/126)
- ddoc (https://github.com/libmir/mir/pull/203)
- harbored: http://docs.mir.dlang.io/harbored/
- adrdox (https://github.com/libmir/mir/issues/32)

A couple of general points:
---------------------------

(warning: this is a small rant)

- the documentation ecosystem is horrible (except for ddox none of these tools
are easy to setup)
- it's pretty damn hard to get something visually appealing
- using custom macros and features of a documentation engine lock one into the
setup
- Imho the reason that no good predefined themes and macros for Ddoc exist is
because (1) it's pretty difficult to hack, (2) because all time is spent on
building tools to avoid Ddoc
- If a project has some kind of documentation, it usually maintains its own
docs engine

-> in the end we cloned dlang.org and patched it, s.t. we can use the setup for
Mir
(http://docs.mir.dlang.io/latest/index.html) and have a similar setup to
Phobos, which was in our case important, because some modules of Mir are
intended to be part of Phobos eventually (after testing them in the wild).

However the patched Makefile
(https://github.com/libmir/mir/blob/master/doc/Makefile) looks still really
messy & I would love to dump it in favor of ddox.

--