Thanks for the detail Raniere. -----Original Message----- From: Raniere Silva [mailto:[email protected]] Sent: Saturday, March 25, 2017 5:32 PM To: Moore, Nathan T <[email protected]> Cc: Naupaka Bruce Zimmerman <[email protected]>; Software Carpentry Discuss list <[email protected]> Subject: markdown file with diffs
Hi Nathan, >> I'm a new maintainer of the python-gapminder lesson. Thanks to help us with the python-gapminder. >> Quick question - When I look at a pull request, specifically the >> markdown file with diffs (files changed), and click the "view" button >> on the upper right, I get a sort-of rendered markdown file but some >> of the markdown remains raw - specifically python code and output. >> Is there another button in github to view what the proposed change >> will look like after final rendering with Jekyl? Should I go to the >> proposer's github.io site to see the rendered file? As Naupaka said, there is no other button. :-( GitHub and Jekyll use different Markdown parsers that are incompatible. You can stop reading here since I will only add a few technical details after this point. :-) There is a few Markdown to HTML parsers write in Ruby. The two more famous are redcarpet, https://github.com/vmg/redcarpet, and kramdown, https://github.com/gettalong/kramdown/, and they are incompatible. As far as I could dig, looks like that GitHub started using redcarpet [1] for their website rendering (Markdown files, including README, issues and pull request, wiki, ...). At some point, GitHub started using their own parser [2] to support user notification, issues and pull request cross-reference, ... but GitHub Pages stayed using redcarpet. In 2016, when GitHub Pages moved to Jekyll 3.0 [3], GitHub pages only supported kramdown as Markdown parser. At that point, your Markdown file could be render different at GitHub (parsed by GitHub own tool) and GitHub Pages (parsed by kramdown). Because different websites use different flavours of Markdown, some people started working in a "common" flavour now know as CommonMark, http://commonmark.org/. Early this month, GitHub announced that they are now using a "patched" version of CommonMark [4]. GitHub Pages continue to use kramdown for now. If you looked at [3] you should be questioning yourself for why we are not using kramdown's GitHub-flavoured Markdown support [5]. We could but it would not solve the problem which is due our use of kramdown's block attributes [6] to style code blocks and call out boxes. There is some discussion on CommonMark community [7] about block attributes but will take more time for a consensus. :-( Bests, Raniere [1]: https://github.com/github/markup/tree/v1.0.2 [2]: https://help.github.com/categories/writing-on-github/ [3]: https://github.com/blog/2100-github-pages-now-faster-and-simpler-with-jekyll-3-0 [4]: https://github.com/blog/2333-a-formal-spec-for-github-flavored-markdown [5]: https://kramdown.gettalong.org/parser/gfm.html [6]: https://kramdown.gettalong.org/quickref.html#block-attributes [7]: https://talk.commonmark.org/t/consistent-attribute-syntax/272/108 _______________________________________________ Discuss mailing list [email protected] http://lists.software-carpentry.org/listinfo/discuss
