Markdeep has some very nice features. I love to be able to have more expressiveness than in regular markdown.

But I am not so sure about the diagramming feature. Writing diagrams as ascii art seems like a PITA to me, especially when you need to update a diagram with new shapes, etc.

For this I prefer PlantUML markdown integration: http://plantuml.com

I use VS Code and it has a nice plugin to handle this.

hobo_mark

I do all my markup, including diagrams (PlantUML and more), in AsciiDoc and I have yet to find a good reason to switch to one of the many markdowns.

rapnie

Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?

geraldcombs

Asciidoctor is in the supported markup list in the GitHub Markup README[1], which means you might need to enable compat-mode for strict AsciiDoc syntax support. The Asciidoctor repository's README.adoc renders just fine[2].

[1] https://github.com/github/markup [2] https://github.com/asciidoctor/asciidoctor