Render RMarkdown (.rmd) as Markdown #343

Merged
merged 1 commit into from Sep 11, 2014

Conversation

Projects
None yet
10 participants
@pchaigno
Contributor

pchaigno commented Aug 7, 2014

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.)

@pchaigno pchaigno referenced this pull request in github/linguist Sep 8, 2014

Closed

Treat RMarkdown like Markdown #990

@jennybc

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

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

jennybc commented Sep 9, 2014

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

@technocrat

This comment has been minimized.

Show comment
Hide comment
@technocrat

technocrat Sep 9, 2014

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

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

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

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.

jennybc commented Sep 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@bkeepers

bkeepers Sep 9, 2014

Member

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?

Member

bkeepers commented Sep 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@vmg

vmg Sep 9, 2014

Member

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

Member

vmg commented Sep 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@pchaigno

pchaigno Sep 9, 2014

Contributor

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#990. They probably know more about the RMarkdown syntax.

Contributor

pchaigno commented Sep 9, 2014

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#990. They probably know more about the RMarkdown syntax.

@ramnathv

This comment has been minimized.

Show comment
Hide comment
@ramnathv

ramnathv Sep 9, 2014

@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

ramnathv commented Sep 9, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@karthik

karthik Sep 9, 2014

'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.

karthik commented Sep 9, 2014

'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

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

+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

jennybc commented Sep 9, 2014

+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

This comment has been minimized.

Show comment
Hide comment
@pchaigno

pchaigno Sep 9, 2014

Contributor

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 :-)

Contributor

pchaigno commented Sep 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

@pchaigno 👍 to your Gist!

jennybc commented Sep 9, 2014

@pchaigno 👍 to your Gist!

@ymendel

This comment has been minimized.

Show comment
Hide comment
@ymendel

ymendel Sep 9, 2014

Contributor

@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.

Contributor

ymendel commented Sep 9, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

@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).

jennybc commented Sep 9, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@technocrat

technocrat Sep 9, 2014

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.

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

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 9, 2014

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.

jennybc commented Sep 9, 2014

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

This comment has been minimized.

Show comment
Hide comment
@karthik

karthik Sep 9, 2014

@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.

karthik commented Sep 9, 2014

@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

This comment has been minimized.

Show comment
Hide comment
@technocrat

technocrat Sep 9, 2014

@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.

@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

This comment has been minimized.

Show comment
Hide comment
@pchaigno

pchaigno Sep 11, 2014

Contributor

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

Contributor

pchaigno commented Sep 11, 2014

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

@ramnathv

This comment has been minimized.

Show comment
Hide comment
@ramnathv

ramnathv Sep 11, 2014

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.

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 bkeepers self-assigned this Sep 11, 2014

@bkeepers

This comment has been minimized.

Show comment
Hide comment
@bkeepers

bkeepers Sep 11, 2014

Member

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.

Member

bkeepers commented Sep 11, 2014

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

This comment has been minimized.

Show comment
Hide comment
@technocrat

technocrat Sep 11, 2014

@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)

@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

This comment has been minimized.

Show comment
Hide comment
@karthik

karthik Sep 11, 2014

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.

karthik commented Sep 11, 2014

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

This comment has been minimized.

Show comment
Hide comment
@bkeepers

bkeepers Sep 11, 2014

Member

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

Member

bkeepers commented Sep 11, 2014

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

@bkeepers

This comment has been minimized.

Show comment
Hide comment
@bkeepers

bkeepers Sep 11, 2014

Member

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 🎩

Member

bkeepers commented Sep 11, 2014

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

This comment has been minimized.

Show comment
Hide comment
@karthik

karthik Sep 11, 2014

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

karthik commented Sep 11, 2014

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

@ramnathv

This comment has been minimized.

Show comment
Hide comment
@ramnathv

ramnathv Sep 11, 2014

This is awesome. Thanks @bkeepers! 👍

This is awesome. Thanks @bkeepers! 👍

@bkeepers bkeepers merged commit 7012598 into github:master Sep 11, 2014

1 check passed

continuous-integration/travis-ci The Travis CI build passed
Details

@pchaigno pchaigno deleted the pchaigno:rmarkdown branch Sep 11, 2014

@karthik

This comment has been minimized.

Show comment
Hide comment

karthik commented Sep 11, 2014

@jennybc

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 11, 2014

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

jennybc commented Sep 11, 2014

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

@ramnathv

This comment has been minimized.

Show comment
Hide comment
@ramnathv

ramnathv Sep 11, 2014

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

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

@pchaigno

This comment has been minimized.

Show comment
Hide comment
@pchaigno

pchaigno Sep 11, 2014

Contributor

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

Contributor

pchaigno commented Sep 11, 2014

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

@bkeepers

This comment has been minimized.

Show comment
Hide comment
@bkeepers

bkeepers Sep 12, 2014

Member

This is deployed now. Enjoy!

Member

bkeepers commented Sep 12, 2014

This is deployed now. Enjoy!

@jennybc

This comment has been minimized.

Show comment
Hide comment
@jennybc

jennybc Sep 12, 2014

This is fantastic! Christmas in SeptembeR.

jennybc commented Sep 12, 2014

This is fantastic! Christmas in SeptembeR.

@gjtorikian

This comment has been minimized.

Show comment
Hide comment
@gjtorikian

gjtorikian Sep 12, 2014

Member

Looks great!

Member

gjtorikian commented Sep 12, 2014

Looks great!

@TanyaMurphy

This comment has been minimized.

Show comment
Hide comment
@TanyaMurphy

TanyaMurphy Aug 25, 2015

I'm a little late but THANK YOU!

I'm a little late but THANK YOU!

@arfon arfon referenced this pull request in github/linguist Dec 3, 2015

Closed

.Rmd not being recognised #2756

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment