Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Render RMarkdown (.rmd) as Markdown #343

Merged
merged 1 commit into from
Sep 11, 2014
Merged

Conversation

pchaigno
Copy link
Contributor

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

@jennybc
Copy link

jennybc commented Sep 9, 2014

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

@technocrat
Copy link

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
Copy link

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor Author

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

@ramnathv
Copy link

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
Copy link

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
Copy link

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
Copy link
Contributor Author

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
Copy link

jennybc commented Sep 9, 2014

@pchaigno 👍 to your Gist!

@ymendel
Copy link
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
Copy link

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
Copy link

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
Copy link

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
Copy link

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
Copy link

@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
Copy link
Contributor Author

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

@ramnathv
Copy link

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
Copy link
Contributor

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
Copy link

@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
Copy link

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
Copy link
Contributor

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

@bkeepers
Copy link
Contributor

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
Copy link

karthik commented Sep 11, 2014

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

@ramnathv
Copy link

This is awesome. Thanks @bkeepers! 👍

@bkeepers bkeepers merged commit 7012598 into github:master Sep 11, 2014
@pchaigno pchaigno deleted the rmarkdown branch September 11, 2014 21:27
@karthik
Copy link

karthik commented Sep 11, 2014

@jennybc
Copy link

jennybc commented Sep 11, 2014

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

@ramnathv
Copy link

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

@pchaigno
Copy link
Contributor Author

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

@bkeepers
Copy link
Contributor

This is deployed now. Enjoy!

@jennybc
Copy link

jennybc commented Sep 12, 2014

This is fantastic! Christmas in SeptembeR.

@gjtorikian
Copy link
Contributor

Looks great!

@TanyaMurphy
Copy link

I'm a little late but THANK YOU!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants