[https://hackmd.io/features](https://hackmd.io/features) is a great document to explore what people have managed to do with markdown.
Likewise, it's hard to say bad things about how the rust documentation turns out in practice: [https://doc.rust-lang.org/std/result/index.html](https://doc.rust-lang.org/std/result/index.html) \- it's all markdown-based, checked by the compiler, directly runnable in the browser etc etc.
