Display R notebooks on github

[DominiqueMakowski]

Is there any integration between github and Rnotebooks? Like the one with jupyter notebooks, that are nicely displayed on github. I've tried to save the notebooks in different formats (.html, .nb.html, .pdf) but it does not work. Moreover, is it a way to integrate interactive features (plots with ggplotly for example)?

Thanks

[RaoOfPhysics]

This would be up to GitHub to render the .nb.html files here. Not sure RStudio can do much about it.

My solution is to use GitHub Pages to render my notebooks. I create directories named after specific notebooks (say, topic), and then have an index.Rmd file that generates the index.nb.html file. I then create a symlink called index.html pointing to index.nb.html so that you can view the content by simply going to ../notebooks/topic rather than ../notebooks/topic/index.nb.html.

You'll need to create the symlinks on a *NIX system and then push it to GitHub, though, as far as I can tell -- I might be wrong!

• e.g. repo: https://github.com/RaoOfPhysics/phd-notebooks
  • The individual notebooks (in their respective directories) are rendered here: https://raoofphysics.github.io/phd-notebooks/
  • Example notebook: https://raoofphysics.github.io/phd-notebooks/benefits/
    • The index.html file in that directory points to https://raoofphysics.github.io/phd-notebooks/benefits/index.nb.html
    • The .Rmd file can be grabbed here: https://raoofphysics.github.io/phd-notebooks/benefits/index.nb.html https://raoofphysics.github.io/phd-notebooks/benefits/index.Rmd

You can also use ggplotly() to make the plots you render interactive. I've not done so for these notebooks, although I have tested it.

[jcvdav]

Agree with @RaoOfPhysics, perhaps this issue belongs to github (unless @yihui can come up with a way to generate a symlink when rendering the notebook, but I am sure there are many reasons not to).

I didn't want to use a first page and then divide by topics, since I just wanted to have a single topic within my repo. On Windows 10, I did it like this:

1. Open a cmd prompt as administrator
2. Navigate to your repo cd "C:\Users\MyName\Documents\GitHub\MyRepo"
3. Generate a symlink with mklink. This is used as mklink "linkfile" "to_this_file". In this case: mklink "index.html" "index.nb.html"
4. Commit and push to your repo

Here is a site working like this

[jjallaire]

@karthik Do you know anyone at GitHub that it would be productive to follow up with on this?

[karthik]

@jjallaire Brandon Keepers might be a starting point (@bkeepers). He helped merge the issue with rendering Rmd files.

[jjallaire]

@bkeepers It would be awesome if we could get R Notebooks to render on GitHub the same way that Jupyter notebooks currently render. This should be very straightforward as R Notebooks are actually valid HTML files that can be rendered as-is (see http://rmarkdown.rstudio.com/r_notebooks.html#notebook_file).

Here's a simple example: https://github.com/karthik/rmarkdown-notebook/blob/master/test.nb.html

If the .nb.html file was rendered inside an iframe (the same way that Jupyter notebooks are currently rendered) then that would be all we need.

Let us know if there is someone at GitHub we should be working with on this. We are happy to do any implementation legwork required if you let us know what the shape of this work is.

[yihui]

Hi @bkeepers, we just want to check again if there is a chance to support R Notebooks on Github, since many users have expressed interest in it. Thanks!

[bbrewington]

I reached out to Github Support via email and they responded today:

I'm currently discussing with the team internally where would be the best place to report your request to get some notice.

We should be back in touch soon!

[eacunafer]

It is possible to publish my R notebooks in Github. I followed these steps: a) I installed the R kernel in my Jupyter environment. b) I run my R commands in Jupyter using the R kernel c) I downloaded it and saved it as an ipynb file.
d) I uploaded this file to my Github repository. Clicking the file the R notebook is shown. You can see my R notebook at https://github.com/eacunafer/Rlabs-para-Analisis-de-datos/blob/master/r_notebook1.ipynb The only drawback is that other users do not have a way to known is the notebook is for Python or R, due to the extension of the file. But I think this can be fixed.

[RaoOfPhysics]

Hi @eacunafer. Indeed, that solution works for those using Jupyter Notebooks, but it won't work for those of us who use R Notebooks instead.

[eacunafer]

You are right. But My advice for people interested in data science is to learn both R and Python

[RaoOfPhysics]

@eacunafer: Of course, but that's not the point of this issue. And FYI, you can use python within R Notebooks if you want.

[bbrewington]

Below is the last thing I heard on this in an email 1/25/18 from the github team. As of 3/21/18 haven't seen anything pop up on their blog.

Our issue tracker isn't publicly accessible, but you can keep up to date with new features by following our blog: https://github.com/blog

(To keep an eye on it, I set up a google alert for "notebook site:blog.github.com")

[TheMitchWorksPro]

I like to put preview hyperlinks to documents of interest on my projects. If those files are HTML, I can use the htmlpreview syntax in my target and the page will display.

sample target url:

http://htmlpreview.github.com/?https://github.com/TheMitchWorksPro/DataTech_Playground/blob/master/R_Misc/TMWP_CrapsGameSimulation_R.html

Example readme where this is used:

https://github.com/TheMitchWorksPro/DataTech_Playground/blob/master/README.md

I have both Python and R Jupyter notebooks on my project as well. Both preview if you click the link to view the individual file on GitHub. But I do not yet see a simple way to build a hyperlink target for them to use in my readme.md file like what I did with HTML above. Given the content of this issue, it would be great (if possible) if the solution you deployed took a form that enabled this capability.

A possible hack I am experimenting with, but this may break and have to be edited each time I roc-commit the content ... This URL seems to work right now:

https://render.githubusercontent.com/view/ipynb?commit=24a4a32ee885d4ceb6166c83331decc2a44ed900&enc_url=68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f5468654d69746368576f726b7350726f2f44617461546563685f506c617967726f756e642f323461346133326565383835643463656236313636633833333331646563633261343465643930302f525f4d6973632f525f4d616769635371756172655f4578706c6f726174696f6e2e6970796e62&nwo=TheMitchWorksPro%2FDataTech_Playground&path=R_Misc%2FR_MagicSquare_Exploration.ipynb&repository_id=87484008&repository_type=Repository#ff6e4cb6-05b3-43c9-96d8-3117f999122f

Above is source of the iframe on the page for my R notebook where git displays it. I tried hacking together the target of the desired R Notebook with the start of the above but this formed an invalid request (probably to be expected given all the arguments that make the above possible):

https://render.githubusercontent.com/view/ipynb?https://github.com/TheMitchWorksPro/DataTech_Playground/blob/master/R_Misc/R_MagicSquare_Exploration.ipynb

[mwouts]

I agree with @RaoOfPhysics that rendering the .nb.html file would be the cleanest resolution for this.

Until then, you could post to GitHub a Jupyter notebook generated from the .Rmd file. This is similar to what @eacunafer already suggested - I'm only pointing here at how to (semi) automatically generate the .ipynb file.

Requirements

• jupyter, and a R kernel
• A package that allows conversion/edition of .Rmd files as notebooks in Jupyter, among notedown (many github stars), ipymd, this fork (seems to offer a command line conversion between .nb.html and .ipynb) or nbrmd (mine)

In the case of nbrmd, a synchronized .ipynb notebook is maintained up-to-date. Outputs are stored there, while inputs are taken from the .Rmd. This means you can edit the .Rmd file in both rstudio and jupyter, and will just need to refresh and re-execute the notebook in Jupyter (with a R kernel) before exporting the .ipynb to Github.

[msaharia]

Has there been an update to this issue? A simpler way of displaying R Notebooks like Jupyter notebooks would be great!

[jjallaire]

@bkeepers Is there an up to date contact at GitHub who we could follow up with on this? I think it would be relatively straightforward to implement (mostly just a matter of sandboxing the notebook as you already do for ipynb -- no "rendering" will be required since the notebook is already in HTML format).

[williamcodes]

@bkeepers any word on this?

[cbrnr]

As a workaround for now, rendering as github_document might be an option: https://rmarkdown.rstudio.com/github_document_format.html

[ulf1]

I would also love to have this feature. I often use Jupyter notebooks for demo and examples because I know it will render on github. The same should be possible with Rmd files. (The purpose is kind of the same but with less json clutter... off topic...) I mean github will go through the trouble run something like nbconvert to render ipynb to html. Why are they not able to render Rmd to html? That does not make any sense as an excuse.

[modche]

Yes, rendering of Rmdfiles would be really nice!

[helloicyvodka]

Can anyone make an addin to do this automatically? That would be great!

[achungerford]

Would love an update on this issue from the Microsoft/Github dev team.

[mattiasvillani]

How is this still not implemented on GitHub? Seems like such a simple thing. And R has a pretty large user base.

[TS404]

Might as well add my support for this. I've only just discovered using R notebooks rather than just plain workflow scripts and it'd really changed how I work.

[mwilson19]

I agree, seriously no update on this? I would really benefit of sharing nb.html files here....

[modche]

I agree, seriously no update on this? I would really benefit of sharing nb.html files here....

Yes, any update on this? Would be so nice...

[yihui]

Unfortunately, no. We contacted Github Support (twice, I think, in 2018 and 2019), and there has not been any update yet.

[jjallaire]

Perhaps @revodavid could help out with this? David, currently Jupyter notebooks ipynb files are rendered in GitHub within an iframe. The R equivalent is the .nb.html file which could also be rendered in the same sort of iframe. It would be extremely useful to be able to publish these notebooks to GitHub. Anything you can do to get this going in the right direction would be much appreciated.

[revodavid]

I understand that Rmd files are no longer rendered on Github at @yihui's request.

The way I handle this is to add a gh-pages branch to the repository and then link to the HTML directly (say, from README.md), as in this example.

[jjallaire]

We're not talking about Rmd files, we're talking about fully rendered R Notebooks (.nb.html files). These are roughly analogous to .ipynb files in that they contain both code and output (as distinct from Rmd files). They are very easy to render since they are just HTML. If the HTML was put in an iframe like .ipynb currently is it would be extremely useful.

[modche]

We're not talking about Rmd files, we're talking about fully rendered R Notebooks (.nb.html files). These are roughly analogous to .ipynb files in that they contain both code and output (as distinct from Rmd files). They are very easy to render since they are just HTML. If the HTML was put in an iframe like .ipynb currently is it would be extremely useful.

Yes, exactly. Thanks @jjallaire for clarification!

[revodavid]

Ah sorry @jjallaire, I misunderstood. If you or @yihui can loop me in on the email thread with the last response from the GitHub team on the issue, I can see if I can chase it down. Microsoft and GitHub operate as completely independent companies, but I have a couple of contacts I can ask.

[jjallaire]

This issue thread is the extent of our communication with the GitHub team (@yihui are you aware of any other communications?)

[bbrewington]

@revodavid I just forwarded you the email chain w/ github support staff in 2018. Referenced in this comment above: https://github.com/rstudio/rmarkdown/issues/1020#issuecomment-375122566

[yihui]

@jjallaire Yes, we have an email thread started by @bbrewington in 2018, which was just forwarded to @revodavid. Thanks @bbrewington!

[bbrewington]

@revodavid just for clarity, below is the solution we're proposing - https://github.com/rstudio/rmarkdown/issues/1020#issuecomment-320504839

As of 5/13/20 it has 66 thumbs up's, and is the highest "upvoted" comment in this thread

@bkeepers It would be awesome if we could get R Notebooks to render on GitHub the same way that Jupyter notebooks currently render. This should be very straightforward as R Notebooks are actually valid HTML files that can be rendered as-is (see http://rmarkdown.rstudio.com/r_notebooks.html#notebook_file).

Here's a simple example: https://github.com/karthik/rmarkdown-notebook/blob/master/test.nb.html

If the .nb.html file was rendered inside an iframe (the same way that Jupyter notebooks are currently rendered) then that would be all we need.

Let us know if there is someone at GitHub we should be working with on this. We are happy to do any implementation legwork required if you let us know what the shape of this work is.

[cbrnr]

IDK but I thought that like .ipynb files it would be nice if GitHub rendered .Rmd files directly (so not HTML).

[jjallaire]

Rmd files are just markdown source code (no output). What we are proposing here is to render the .ipynb equivalent (source and output) for R Notebooks, which is the .nb.html file.

On Wed, May 13, 2020 at 1:56 PM Clemens Brunner notifications@github.com wrote:

IDK but I thought that like .ipynb files it would be nice if GitHub rendered .Rmd files directly (so not HTML).

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/rstudio/rmarkdown/issues/1020#issuecomment-628150698, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAZPR5YEDFYJWUP3SVCFDLRRLNLRANCNFSM4DIUZ4FQ .

[cbrnr]

Got it, I forgot that .ipynb files contain the previously computed output.

[bbrewington]

@jjallaire would you be able to help provide the specific requirements to @revodavid? See quote from email below. He did mention there may be security concerns of rendering the .nb.html directly as HTML on github (for example, Jupyter Notebooks are queued up to a service that renders them, and there is also nbviewer)

Or if you'd like to hop on the email thread w/ David, I'm happy to add you to it. My email is in my profile - send me yours and I can Cc you on the message?

Text from David's last email on this:

I do want to make sure that I provide the GitHub team with crystal-clear requirements though, and I’m still a bit confused. It’s not exactly the same as Jupyter notebooks right, which are rendered – this is more about displaying raw HTML, right? And do you expect that to happen when viewing the .nb file or the .nb.html file? Can you point to other examples of GitHub rendering HTML directly within the GitHub UI? (I can’t think of any, which makes me think there may be security implications or something like that.)

Sorry to be pedantic, but I expect the GitHub team will have no context for R or RStudio. I do have that context and I myself was confused at first.

If you could you spell out exactly what you want to have happen, that would help me on my end.

[jjallaire]

Hi Brent, just sent you an email so we can follow up on the thread there as necessary. The basic gist is that an R Notebook is "just" HTML with a special file extension to distinguish it (.nb.html).

It would therefore need to be rendered inside an iframe (which is currently how ipynb files are rendered on GitHub). That said, the .nb.html can have arbitrary JavaScript within in, so that might rule out rendering on the main github.com domain (but perhaps there's a way to sandbox the iframe sufficiently, not sure what your policies/practices are there?).

For ipynb it looks like you currently render it into HTML (and presumably do so in a manner which is considered safe for hosting in an iframe on github.com). We could do the same thing for .nb.html (basically pull out the important bits and do a custom "safe" HTML rendering). We'd be happy to write that code and either open-source it or assign it to GitHub, but we'd need some guidance as to what implementation language would be ideal.

[tsantunes]

Hi, I've converted my repository to a page https://[yourname].github.io/[yourrepository]/[yournotebook.nb.html] change the settings/GitHub Pages. Now it's possible to render the HTML file do R notebook like a Jupiter notebook for display my R code.

[modche]

Hi, I've converted my repository to a page https://[yourname].github.io/[yourrepository]/[yournotebook.nb.html] change the settings/GitHub Pages. Now it's possible to render the HTML file do R notebook like a Jupiter notebook for display my R code.

Thx. I could not follow your post, is it possible to see the example?

[tsantunes]

Hi, I've converted my repository to a page https://[yourname].github.io/[yourrepository]/[yournotebook.nb.html] change the settings/GitHub Pages. Now it's possible to render the HTML file do R notebook like a Jupiter notebook for display my R code.

Thx. I could not follow your post, is it possible to see the example?

Hi,

1. go to the repository which you put the R notebook e press settings. In this case, my file HTML is in a subfolder (TESTE1) of the repository (TESTE).

2. after, search for GitHub Pages and select a master branch. Will appear the path for the repository, in this case, https://tsantunes.github.io/TESTE

3. then use the HTML file with the page created considering the subfolders if you have. In this case, my file HTML is in a subfolder (TESTE1) of the repository (TESTE).

https://tsantunes.github.io/TESTE/TESTE1/teste%20notebook.nb.html

Done!

[brianmsm]

Hi, I've converted my repository to a page https://[yourname].github.io/[yourrepository]/[yournotebook.nb.html] change the settings/GitHub Pages. Now it's possible to render the HTML file do R notebook like a Jupiter notebook for display my R code.

Thx. I could not follow your post, is it possible to see the example?

Hi,

1. go to the repository which you put the R notebook e press settings. In this case, my file HTML is in a subfolder (TESTE1) of the repository (TESTE).

1. after, search for GitHub Pages and select a master branch. Will appear the path for the repository, in this case, https://tsantunes.github.io/TESTE

1. then use the HTML file with the page created considering the subfolders if you have. In this case, my file HTML is in a subfolder (TESTE1) of the repository (TESTE).

https://tsantunes.github.io/TESTE/TESTE1/teste%20notebook.nb.html

Done!

This works for me!

[modche]

The point is that the nb.html files are not rendered on github whereas the .ipynb are rendered see this example. You are proposing an alternative by deploying the R markdown output on a github.io site. These are two different things, I guess.

[tsantunes]

The point is that the nb.html files are not rendered on github whereas the .ipynb are rendered see this example. You are proposing an alternative by deploying the R markdown output on a github.io site. These are two different things, I guess.

Yes, I agree. My focus was finding an alternative for display R notebooks on GitHub like a file ipynb. This works for me! Happy to help.

[modche]

Hi. Any updates here?

[bbrewington]

Here's the latest from the email thread (from 2020-07-27)

@revodavid:

Sorry, I didn’t have any luck pursuing this with the GitHub team. I did get a recommendation from Martin Woodward that https://github.community/ is the place the team looks to for community requests – if you haven’t posted there, that may be worth a try

@jjallaire:

That's too bad but thank you in any case for making the effort. Maybe we just need a few hundred upvotes on that issue to get their attention

[shntnu]

Meanwhile, I've needed to resort to this very painful workaround to toggle between interactive analysis and publishing on GitHub.

My colleagues bypass all this by using Jupyter notebooks instead e.g. https://github.com/broadinstitute/cell-health/blob/master/3.train/2.visualize-binary-distribution.ipynb, which, happily, can be rendered.

Whoever implements what I suspect should be a relatively simple feature https://github.com/rstudio/rmarkdown/issues/1020#issuecomment-320504839 and would us so many hours of research time!