conflr: Publishing R Markdown documents on Confluence

I’m Hiroaki Yutani from Data Analysis team, Data Labs. Today, I’m happy to announce conflr (pronounced as confl-R), an open source R package for publishing R Markdown documents on Atlassian Confluence. In this post, I’ll briefly explain the motivation; why we need this, and how to use conflr.

A gap between R Markdown and Confluence

Confluence is one of the greatest tools for documentation. Our team also utilizes it for sharing reports and various kinds of knowledge. On the other hand, to R users, R Markdown is the de facto standard of documentation. But, there’s a huge gap between R Markdown and Confluence. To publish R Markdown reports on Confluence, we had no choice but to copy and paste the code and figures. This is very frustrating. No matter how hard we try to build a reproducible workflow by R Markdown, that reproducibility is interrupted if we choose Confluence for sharing reports.

conflr was made for filling this gap. By using conflr, we can directly upload R Markdown reports to Confluence.

Installing conflr

conflr is not released on CRAN. You can download and install it from GitHub by using the devtools devtools::install_github() function on RStudio console.

devtools::install_github("line/conflr")

For conflr to access the Confluence API, conflr needs the following information set as environment variables.

  • The base URL of your Confluence site (CONFLUENCE_URL)
  • Your username (CONFLUENCE_USERNAME)
  • Your password (CONFLUENCE_PASSWORD)

You have two ways to set the variables. First is to enter the environment variables in the popups that are displayed when you run the install command.

You can either input via the following popups on function execution.

Another way is to set the variables in the ~/.Renviron file. For example, you can set the base URL in the file as the following.

CONFLUENCE_URL=https://confluence.example.com

Using conflr

conflr is an RStudio addin. After you install conflr, you will be able to see the Post to Confluence menu in the Addins dropdown list on RStudio. Let’s learn how to add and update a page.

Post to Confluence menu added on RStudio

Adding a new page

Let’s see how to add a new page on your Confluence site. First, open an R Markdown file you want to publish in RStudio. Select the Post to Confluence menu while the file is active. conflr starts to knit the file.

After knitting, a preview of the page is displayed as below:

A preview of a Confluence page

If you are okay with the knitted document, fill in the following fields on the window:

  • type: The type of the page (page means a normal wiki page, whereas blogpost mean a blog post, not a page).
  • Space Key: The key of the space you want to post (if you don’t know the key, you can open any of the space page on a web browser, go to Overview in the Space tools menu at the bottom-left of the page).
  • Parent page ID (optional): The ID of the parent page to the page.

Once you fill out the fields and are ready to proceed, click the Publish button at the top-right. Then, the document will be uploaded to your Confluence. When uploading is finished, conflr automatically launches a web browser and jumps to the page created on Confluence. Here is a screenshot of the example page we created.

A Confluence page created from R Markdown file

Updating an existing page

To update an existing page, just click the Post to Confluence menu again with the updated R Markdown file. conflr will overwrite the page with the same title in the specified space.

Summary

conflr makes your life simple by bridging R Markdown and Confluence. Although it cannot translate all of R Markdown to Confluence’s syntax, conflr supports images, tables, and simple Math equations. If you find a bug, please let us know by filing an issue at https://github.com/line/conflr/issues.