fix link to markdown file and document some of the markdown magic that github does