Gollum: Feature request: RMarkdown Support

[ogurcan]

It would be great if Gollum support RMarkdown and allow creating Wikis using RMarkdown.

[bartkamphorst]

@ogurcan What would be needed for this? Availability of pandoc, R and rmarkdown R package?

[ogurcan]

I am not an expert but I suppose yes, pandoc, R and rmarkdown R package. RMarkdown already supports very nice features like embedding R code, creating R notebooks etc. When RMarkdown is added, gollum can be a unique scientific wiki-like note taking environment also.

[dometto]

I have no experience with RMarkdown, but would it be possible to do this by tweaking the configuration of pandoc here?

[bartkamphorst]

Seems like pandoc might not even be strictly necessary: https://rmarkdown.rstudio.com/authoring_quick_tour.html as knitr outputs .md files.

[shrysr]

I guess it would be nice if Gollum supported Rmd out of the box so +1 for this since I use R. Afaict - the only difference between md and Rmd is that the code chunks are defined a little differently. Rmd is interesting particularly because, like Org mode documents (and unlike Jupyter notebooks in general), it is possible to store code notebooks in a text markup format, enabling version control.

P.S I've ~almost decided in using Gollum for my personal wiki. Being an Emacs + Org mode guy - I'm swayed by the git integration and the way Org files are directly rendered. Maybe this would also help with clues > https://github.com/chasberry/orgmode-accessories

[dometto]

The main development principle I would like to maintain is: gollum is not responsible for rendering documents itself. That means we need a 'third party' library or app like Pandoc to function as a renderer. Just found these:

• rubydown
  
  
  
  • doesn't seem as widely used as one would like
  
  
• galaaz
  
  
  
  • I don't know to what extent gKnit conforms to ordinary RMarkdown -- anyone able to comment on this?
  
  
  • it requires TruffleRuby
  
  

@shrysr thanks for pitching in. Since the main business of RMarkdown involves parsing code blocks, we may have to skip Gollum's codeblock rendering step altogether for RMarkdown documents (using the skip_filters directive, as e.g. here), or make an exception for executable code blocks.

Re: your other comments, @shrysr: great to have you aboard! If you have any specific ideas of how org-mode support could be improved, feel free to open new issues -- although see again the design principle I outlined above: gollum's support of org-mode is limited by what the rendering gem, in this case org-ruby, can do. It would be great to know if this is still up to date, if there are alternatives, and if we're currently using all its features.

[dometto]

Anyone interested in helping with this please see https://github.com/gollum/gollum-lib/pull/397

[dometto]

@ogurcan or anyone else watching this thread: could you give us some feedback on how, as an RMarkdown user, you would expect this to work in gollum? When viewing a page, should all the RMarkdown blocks already be rendered (also displaying the original R code, unless echo = FALSE )? Or should it first display the code blocks, only rendering them when a user presses a button? The first would be the easiest to implement, but it would be good to know what a typical RMarkdown workflow would look like.

[ogurcan]

Typically, it is the first case. You can even by default hide the original R code and make it optional to show it as it fits better for a Wiki-like usage of RMarkdown.

[dometto]

After having experimented with this a while, @bartkamphorst and I have concluded the following:

• There are serious security concerns attached to RMarkdown rendering. Opening a wiki page containing an RMarkdown block basically allows whoever wrote that page to execute arbitrary code on the machine running gollum.
  
  
  
  • This is a problem, obviously, for users who run gollum as a server app.
  
  
  • However, it is also a problem for users who run gollum locally, when opening a wiki page from an untrusted source.
  
  
• So the only way we can see of integrating RMarkdown support in gollum is by executing the R code elsewhere: on a different machine, or in a container.
• As far as we're aware, there does not yet exist a server app that simply returns the result of an RMarkdown codeblock. Fortunately, such an app can be quite simple. Enter rmarkdownserve, a quickly written sinatra app (like gollum) that takes in RMarkdown blocks via HTTP POST, executes them, and returns the rendered result.
  
  
  
  • Any help improving this project is very welcome!
  
  
• RMarkdown integration in gollum would work like this:
  
  
  
  • User runs rmarkdownserve in a Docker container
  
  
  • User tells gollum where it can find rmarkdownserve (default: localhost)
  
  
  • When opening a page, gollum issues an AJAX request, replacing RMarkdown blocks on the page with the results rendered by rmarkdownserve.
  
  
  • We can optionally let gollum try to run the Docker container for rmarkdownserve on startup.
  
  

@ogurcan and anyone else interested in RMarkdown support: does this sound like an acceptable solution? Any feedback and help is very welcome!

[ogurcan]

I think that this sounds like a fair and acceptable. Thanks in advance!