https://issues.dlang.org/show_bug.cgi?id=16112
--- Comment #8 from [email protected] --- > 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. --
