I've entirely replaced markdown and been using asciidoctor for both documentation and general writing.
Asciidoctor is far superior to Markdown and as easy to use and is also supported on Github.
Asciidoctor is far superior to Markdown and as easy to use and is also supported on Github.
(Note: This appears to be written by the AsciiDoc team)
I'll use an example: I often need to create "Warning Notes" (aka "Admonitions") in my documentation. Those notes need to stand out, but they also need to not break the flow of reading. I need them to be visible, but easy to spot with the eye and ignore. It makes reading the doc and ignoring less important information easier. With Markdown, I can't create those notes.
Other interesting and useful thing is the ability to use variables. This allows me to make the documentation dynamic. Imagine, for example, a documentation that has many CURL requests examples that must include an X-Auth-Token. I can dynamically generate the documentation with the Auth-Token of the user reading the doc, allowing them to Copy/Paste the examples without having to modify them first.
I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.
For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.
Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL.
I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.
It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc.
I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you.
The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others.
How does asciidoc do it?
[1] http://www.oilshell.org/blog/
[2] https://github.com/oilshell/blog-code/tree/master/tools-snap...