Markdown for documentation ?

I agree that Markdowns 1-to-1 relationship with HTML is problematic at best.

Markdown is really good at what it does – it is somewhat easy to learn and it is widespread already.

Introducing new alternatives at this point – even though they might be better – might prove a pointless effort.