Investigate alternative Markdown renderer

[migurski]

There are some incompatibilities between Github’s Markdown parsing and Python’s:

• Anchor links are different
• Linebreaks before lists are different
• Ordered lists with images are different

@rmglennon can you add links to example in the comments. Also, possible code with a solution: https://github.com/Zopieux/py-gfm

[rmglennon]

Anchor links: See issues https://github.com/tangrams/tangram-docs/pull/139#issuecomment-241562380

Linebreaks: Python markdown requires a line break before any formatting change. This is commonly experienced in unordered lists. Without the extra line, you will get text and then see the raw dashes.

Ordered lists:

https://mapzen.com/documentation/mobility/explorer/explore-transit/#explore-transit-routes https://github.com/valhalla/valhalla-docs/blob/master/explorer/explore-transit.md#explore-transit-stops-and-travel-times-from-them In this case, the markdown breaks had to be formatted like this because adding extra line breaks to make the spacing around the image caused the numbering to restart at 1 on the other side of the image (yet it looked great in GitHub-Flavored Markdown). The intent is for Here is the and the image to be on new lines and indented under the previous paragraph.

[rmglennon]

See also link problems in https://github.com/mapzen/mapzen-docs-generator/issues/242

[rmglennon]

Also this doc captures an email lou sent out ages ago about markdown formatting (the images don't show, but that's as expected because they were not added to the md file, just inline in the email)

https://github.com/mapzen/styleguide/blob/master/src/site/guides/markdown-style.md