Edits and fixes based on review.

Docker-DCO-1.1-Signed-off-by: Fred Lifton <fred.lifton@docker.com> (github: fredlf)
MkDocs use Markdown.

It would be wonderful to see a custom built MD parser that actually works well - and that supports GH MD 100%.

I would like to remain hopeful but can not help being a little bit doubtful.