Render RMarkdown (.rmd) as Markdown

[pchaigno]

This PR makes RMarkdown files (.rmd) rendered as Markdownl.
If I'm right, this should enable rendering for .rmd files in Gist? (It would be better than the current situation where there is no rendering at all.)

[jennybc]

I would dearly love R Markdown files to have syntax highlighting. So +1 for that functionality.

[technocrat]

I don't think that's the right way to go since it will conflict with the tangled web of linguist/Pygments.rb/payments.py that seems to be behind everything. Better, I think, is to generate an .md file with knitr with the results shown in https://gist.github.com/technocrat/113aefb0b0c62f621815 and to require it to be rendered in the Gist as *markdown rather than RMarkdown

[jennybc]

When an R Markdown document exists, it is the source document, relative to any downstream Markdown documents (or HTML, .docx, PDF, etc.). In some workflows, one would commit only the .[Rr]md and would not necessarily commit the resulting .md.

R Markdown and the associated Markdown files are fundamentally different. One is pure source, whereas the other is an automatically generated hybrid of source and results.

While I appreciate GitHub's excellent handling of Markdown documents, I believe syntax highlighting of R Markdown documents remains a very useful feature.

[bkeepers]

I'm not well-versed in RMarkdown, so I want to make sure I understand: it looks like a superset of markdown. Rendering it as plain markdown would just present R blocks as code blocks. Sound right?

If that's the case, I'm 👍. @gjtorikian, @vmg, @ymendel?

[vmg]

First time I hear of RMarkdown. If it has builtin R documents, I think rendering it with our Markdown renderer will provide weird results.

[pchaigno]

I'm not well-versed in RMarkdown, so I want to make sure I understand: it looks like a superset of markdown. Rendering it as plain markdown would just present R blocks as code blocks. Sound right?

I don't know RMarkdown either but that is what I understood too.

@TanyaMurphy and @karthik requested this in github-linguist/linguist#990. They probably know more about the RMarkdown syntax.

[ramnathv]

@vmg Rmarkdown documents can be rendered exactly the same way as markdown documents get rendered. Currently, I just rename my rmd files as .r.md files to get them rendered in github, but enabling rmd directly will be of immense value to all R users.

Here is an example of a .R.md file.

https://github.com/htmlwidgets/datamaps/blob/master/README.R.md

[karthik]

'm not well-versed in RMarkdown, so I want to make sure I understand: it looks like a superset of markdown. Rendering it as plain markdown would just present R blocks as code blocks. Sound right?

If that's the case, I'm . @gjtorikian, @vmg, @ymendel?

@bkeepers That is exactly the point we are making. Since those of us that practice reproducible research don't always commit files that can be generated, it would help to have these syntax highlighted the same way you do for regular markdown. All the unrendered code blocks should look like regular code blocks with R (or S) syntax highlighting applied.

[jennybc]

+1 to what @ramnathv and @karthik have said.

In case we haven't made this clear, in the R world, we render foo.Rmd to foo.md, where the R code chunks are replaced (potentially) by the outputs they produce. Then foo.md is compiled to foo.html. The intermediate Markdown is not necessarily retained (thought I make this a habit, largely because of the GitHub's Markdown handling). So making R markdown a first class format w/r/t GitHub syntax highlighting would be awesome.

Here's one example of an rOpenSci repo (and R package) with a README.Rmd (there are many others):

https://github.com/rOpenGov/enigma/blob/master/README.Rmd

[pchaigno]

Here's one example of an rOpenSci repo (and R package) with a README.Rmd (there are many others): https://github.com/rOpenGov/enigma/blob/master/README.Rmd

Here is what it would produce if this PR is merged:
https://gist.github.com/pchaigno/ee39c02b09d51116ac85
It looks like it would work really well :-)

[jennybc]

@pchaigno 👍 to your Gist!

[ymendel]

@bkeepers: Based on what I've seen here (especially the gist @pchaigno provided), this seems more than fine.

It would be great if we could make it so https://github.com/rOpenGov/enigma/blob/d3949d8ed7383f06680be4d15898d2a6fa7ff78a/README.Rmd displayed like https://github.com/rOpenGov/enigma/blob/d3949d8ed7383f06680be4d15898d2a6fa7ff78a/README.md, but that's a separate effort.

[jennybc]

@ymendel: If I understand your last comparison correctly … I don't think that is necessarily a reasonable(?) goal. Because that would require running all those R chunks, which heads more into the territory of, say, hosting iPython notebooks. Agree that is a separate effort (but also potentially fantastic).

[technocrat]

I'm finding that different implementations of Markdown handle parsing of triple backticks inconsistently. The proposed specification for Common Markdown at https://github.com/jgm/stmd has a rigorous treatment of the rules for code blocks and any modification to GFM should be written to pass the CM test suite and RMarkdown within R, using knitr, should too.

That way jennybc's goals of keeping a single .Rmd source file that would be accurately rendered as a gist without having first to be converted to md could be realized and if other Markdown implementations were similarly conformed, the knitr conversion step could also be eliminated for many other purposes.

[jennybc]

jennybc's goals of keeping a single .Rmd source file that would be accurately rendered as a gist without having first to be converted to md

This is not what I am asking for.

[karthik]

@technocrat writes:

That way jennybc's goals of keeping a single .Rmd source file that would be accurately rendered as a gist without having first to be converted to md could be realized and if other Markdown implementations were similarly conformed, the knitr conversion step could also be eliminated for many other purposes.

This is absolutely not what we are asking for.

[technocrat]

@jennybc @karthik Since I misinterpreted that one (read as native support), assuming that knitr won't be modified to produce CM compliant md files, then GFM needs a way of identifying files converted that way and running a preprocessor to make it compliant. I ran @jennybc 's sample against the stmd suite and the html came out wretched as far as the code blocks went. Pygments should work ok if R code is properly wrapped.

[pchaigno]

Are there still concerns or is it ready to be merged?

[ramnathv]

Maybe I am missing something completely here, but all that is needed to render an Rmd document in github is to recognize it as a valid markdown extension. Nothing more is needed IMHO.

[bkeepers]

I just need to test it to make sure there aren't any weird side-effects and that .rmd docs look good when they're rendered. It's on my list to do today.

[technocrat]

@brandon -- just because this has been a somewhat jagged thread, the two issues are

Codeblocks and within codeblocks syntax highlighting
—
Sent from Mailbox

On Thu, Sep 11, 2014 at 10:50 AM, Brandon Keepers
notifications@github.com wrote:

I just need to test it to make sure there aren't any weird side-effects and that .rmd docs look good when they're rendered. It's on my list to do today.

Reply to this email directly or view it on GitHub:
#343 (comment)

[karthik]

Thanks @bkeepers!
Let us know if you need a bunch of Rmd files already in my repos that you'd like to test before the deploy.

Cheers.

[bkeepers]

@karthik if you could link to some file in public repos, I would appreciate it.

[karthik]

@bkeepers, here are a handful of files from my accounts:

https://github.com/ropensci/rfigshare/blob/master/inst/doc/vignettes/README.Rmd

https://github.com/ropensci/rfigshare/blob/master/vignettes/README.Rmd

https://github.com/ropensci/rbison/blob/master/vignettes/rbison_vignette.Rmd

https://github.com/ropensci/ecoengine/blob/master/inst/Using_ecoengine.Rmd

https://github.com/ropensci/taxize/blob/master/inst/vign/taxize_vignette.Rmd

[bkeepers]

This is looking great on the docs I have tested. I'll combine this with a few other PRs, make a new release of github-markup, and push it to GitHub. Hold onto your 🎩

[karthik]

Fantastic! Thanks @bkeepers! 🍻 on me when we meet.

[ramnathv]

This is awesome. Thanks @bkeepers! 👍

[karthik]

[jennybc]

I knew @karthik would have just the right GIF for this.

[ramnathv]

Awesome! So when will this show up in Rmd rendering?

[pchaigno]

@bkeepers is making a new release so it should show up in just a moment :-)

[bkeepers]

This is deployed now. Enjoy!

[jennybc]

This is fantastic! Christmas in SeptembeR.

[gjtorikian]

Looks great!

[TanyaMurphy]

I'm a little late but THANK YOU!