[chrismorgan]

I’ve seen all kinds of awful README.md files because people are trying to shoehorn stuff into Markdown that doesn’t fit.

The problem with Markdown is that it isn’t simple; rather, it’s simplistic, and quite a few things that should be simple instead require terrible hacks to work around Markdown and use HTML.

reStructuredText is generally quite a bit better in this regard because it focuses on expressing semantics.