I've found markdown failing for me for very simple things.

Someone suggested ASCIIDOC as an alternative with similar feeling of being easily editable and readable as is. This was posted on HN a while ago

https://medium.com/@chacon/living-the-future-of-technical-wr...