Change Markdown rendering to GitHub-flavored renderer

[robbkidd]

A couple of issues have come in that boil down to "Supermarket's Markdown renderer is not Github-flavored." Given the prevalence of community cookbooks whose READMEs are forged in the fires of GitHub, it is reasonable to expect that the README will render similarly on GitHub and on Supermarket.

Opening this issue as a roll-up to investigate configuring the existing renderer or changing it out for something that acts like GitHub's.

Some things to check:

• support language-specific syntax highlighting in code blocks
• does not render <!-- --> HTML comments
• renders tables We do this already.

[robbkidd]

Code syntax highlighting will have to come from Coderay, Rouge, or some other additional text processor to markup the text passed to our custom renderer.

Displaying HTML comments in the markdown appears to be the outcome of escaping the HTML in the custom Renderer.

[nellshamrell]

We will not be getting to this in the next 6 months, but am open to revisiting in the future.

[robbkidd]

Adding options—that I'm not sure how I missed earlier—to this rollup in case it gets reopened in the future:

• https://github.com/github/markup - GitHub's markdown renderer
• https://github.com/github/linguist#syntax-highlighting - GitHub's syntax highlighter

[iennae]

Currently tables that use html table syntax don't render. With #1622 this is fixed so tables do render properly.

[damacus]

We've just noticed another subtle issue with the renderer.

• [install](documentation/resource_apache2_install.md) isn't rendered correctly. This isn't github flavoured though 🤔 it's pretty standard markdown.

[robbkidd]

I can picture how a relative URL like that which works in the context of GitHub won't work on Supermarket because the cookbook's documentation/resource_apache2_install.md (1) isn't packaged with the cookbook artifact and (2) isn't a part of the list of files from a cookbook that are processed for storing the README.

How much work do we want to put into Supermarket duplicating the GitHub experience and content?

[damacus]

I think it would be nice for it to render the markdown to not look broken, even if the link is borked

[robbkidd]

I think it would be nice for it to render the markdown to not look broken, even if the link is borked

Aaaah. I see now. Gotcha. 🤔

[robbkidd]

Relative links got nerfed when we switched to the "safe" version of the markdown renderer. Relative links don't start with a string on the library's safe allow list.

I think while Supermarket is using Redcarpet for markdown rendering, it won't be supporting rendering relative links as links. There's an attempt at switching over to GitHub's own markdown rendering pipeline, but the test failures there need addressing.

[damacus]

I think we have a good work around then, we just won't make them relative and always point at master/blob

[tas50]

I think we've solved this one enough at this point that we can potentially close it out. If we run into additional rendering issues we should raise them 1 at a time to track/fix