Agreed, the main advantage of Markdown is it's easy, so encourages quick ephemeral notes which would otherwise be plain text, and if done properly (i.e., writte

Agreed, the main advantage of Markdown is it's easy, so encourages quick ephemeral notes which would otherwise be plain text, and if done properly (i.e., written as plain text with some extra conventions) is readable as plain text, and you get a pretty view on GitWhatever. If you want big formal documentation, are you sure? It has less value than you think and imposes a maintenance burden which will eat your life. If yes, then use DocBook or LaTeX.