Frequently asked questions

workflowr version 1.3.0

John Blischak

2019-04-15

Why isn’t my website displaying online?

Occasionally your website may not display (or recent updates will not immediately appear), and you may even receive an email from GitHub with the following message:

The page build failed for the master branch with the following error:

unable to build page. Please try again later.

For information on troubleshooting Jekyll see:

https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can contact us by replying to this email.

If you’ve followed the setup instructions from the Getting started vignette, and especially if the website displayed in the past, it’s very unlikely that you caused the problem. The hosting is provided by GitHub Pages, and it sometimes is delayed or down. Overall for a free service, it is very reliable. If you wait 5 minutes (or 30 minutes at most), your website will likely be back to normal.

If you are anxious to know if there is a problem and when it will be resolved, you can check the status of the Twitter account GitHub Status for the most up-to-date reports from GitHub. If you suspect that the problem may have been caused by your recent changes to your website (again, this is unlikely), you can view the GitHub help page Troubleshooting GitHub Pages builds.

Can I make my workflowr website private?

Short answer: Not if you use the default setup that deploys the site on GitHub Pages. For alternative deployment options, see the vignette Alternative strategies for deploying workflowr websites. It includes options for public or private websites.

Long answer: Even if you create a private GitHub repository, the website it creates is still public. If you’re not ready to publish your results online, you can always wait and activate GitHub Pages later. In the meantime, you’ll still have a version-controlled, organized set of results for your project. However, the risk that someone that doesn’t have the link to your website is able to find it is very low. Search engines prioritize the results by how many other sites link to a site, so your website will not be high in the results even if you search for very specific terms. Thus if you only share the URL to your results with your close collaborators, and request that they not share it widely, your website is effectively private. That being said, being truly scooped in science is rare (at best) and openly sharing your work will help establish your expertise in the field (and furthermore establishes your priority), so you should consider keeping both your code and website public. The main caveat to this advice is if you are analyzing data that contains sensitive or restricted information, in which case you should not use GitHub Pages or any other public deployment option.

How can I include external images in my website?

Image files that are generated by the code executed in the R Markdown files are automatically handled by workflowr. If you’d like to include additional image files to be displayed in your webpages, follow these steps:

  1. Create an assets directory to include any file that should be part of the website but is not created by the R Markdown files in analysis/:

       dir.create("docs/assets")
  2. Move the image file(s) to docs/assets/
  3. In the R Markdown file, refer to the image file(s) using the relative path from docs/ (because this is where the HTML files are located), e.g.:

       ![](assets/external.png)
  4. Run wflow_build() to confirm the external image file(s) are properly displayed
  5. Use wflow_git_commit() to commit the file(s) to the Git repo (so that they get pushed to GitHub):

       wflow_git_commit("docs/assets/external.png", "Add external image of ...")
       # If you are adding multiple files, you could use a file glob
       wflow_git_commit("docs/assets/*.png", "Add external images of ...")
  6. Run wflow_publish() on the R Markdown file that contains the external image file(s)

Can I include Shiny apps in my website?

No, at least not in the standard setup. The website is hosted with GitHub pages, which only supports static web pages. Shiny apps are dynamic, i.e. a user can interact with them to change the content. The easiest way to share your Shiny app would be to host it at shinyapps.io and add a link to your app on your workflowr website. Alternatively you could host your workflowr website on your own server, but that would require much more knowledge and resources to accomplish.

Can I change “X” on my website?

Almost certainly yes, but some things are easier to customize than others. The vignette Customize your research website provides some ideas that are simple to implement. Check out the documentation for rmarkdown and Twitter Bootstrap for inspiration.

Why am I not getting the same result with wflow_build() as with the RStudio Knit HTML button?

wflow_build() is designed to have the same functionality as the Knit HTML button in RStudio, namely that it knits the HTML file in a separate R session to avoid any clashes with variables or packages in use in the current R session. However, the technical implementations are not identical, and thus informally we have noticed the behavior of the two options occasionally differs. At the moment, we believe that if the file results in an error when using wflow_build(), the file needs to be fixed, regardless of whether the file is able to be built with the RStudio button. If you have a use case that you think should be supported by wflow_build(), please open an Issue and provide a small reproducible example.

Can I share workflowr websites directly with collaborators in a secure fashion?

Yes. Please see these instructions for deploying a workflowr project securely with Beaker Browser.

Can I password-protect my website?

Yes. Please see these instructions for deploying a workflowr project with password-protection using Amazon S3.

Can I create a single HTML or PDF file of one of my workflowr R Markdown files?

Yes! If you’d like to create a single HTML or PDF file to distribute an isolated analysis from your project, you can directly run the rmarkdown function render.

library("rmarkdown")
# Create analysis/file.html
render("analysis/file.Rmd", html_document())
# Create analysis/file.pdf
render("analysis/file.Rmd", pdf_document())

There are two main caveats to this:

  1. Internal links to other HTML pages in your workflowr site will be broken since they are not being distributed with the single file.
  2. An R Markdown file that can be converted to HTML is not guaranteed to be converted to PDF. You’ll need to ensure that you have LaTeX installed on your computer and avoid complicated characters and/or syntax.

Can I use R notebooks with workflowr?

Yes! You can use RStudio’s notebook features while you interactively develop your analysis, either directly using the output format rmarkdown::html_notebook() or indirectly with “inline code chunks” in your R Markdown files. However, you need to take a few precautions to make sure your notebook-style usage is compatible with the workflowr options.

First note that the R Markdown files created by wflow_start() and wflow_open() include the lines below in the YAML header. These purposefully disable inline code chunks to proactively prevent any potential incompatibilities with workflowr. To activate inline code chunks, you can either delete these two lines or replace console with inline.

editor_options:
  chunk_output_type: console

Second, note that the working directory of the inline code chunks can be different than the working directory of the R console. This is very counterintuitive, but the working directory of the inline code chunks is set by the “Knit Directory” setting in RStudio. The setting of “Knit Directory” may be different in your collaborator’s version of RStudio, or even your own RStudio installed on a different computer. Thus it’s not a good idea to rely on this value. Instead, you can explicitly specify the working directory to be used for the inline code chunks by setting the knitr option root.dir in a chunk called setup, which RStudio treats specially. Adding the code chunk below to your R Markdown file will cause all the inline code chunks to be executed from the root of the project directory. This is consistent with the default workflowr setting.

```{r setup}
knitr::opts_knit$set(root.dir = "..")
```

If you change the value of knit_root_dir in _workflowr.yml, then you would need to change the value of root.dir in the setup chunk accordingly. Warning that this is fragile, i.e. trying to change root.dir to any arbitrary directory may result in an error. If you’re going to use inline code chunks, it’s best two follow one of the following options:

  1. Execute code in the root of the project directory (the default workflowr setting). Don’t change knit_root_dir in _workflowr.yml. Add the setup chunk defined above to your R Markdown files. Note that this setup chunk will affect RStudio but not the workflowr functions wflow_build() or wflow_publish().

  2. Execute code in the R Markdown directory (named analysis/ by default). Delete the knit_root_dir entry in _workflowr.yml. Don’t explicitly set root.dir in a setup code chunk in your R Markdown files. Ensure that the RStudio setting “Knit Directory” is set to “Document Directory”.

Third, note that if you are using html_notebook(), any settings you specify for it will be ignored when you run wflow_build() or wflow_publish(). This is because the settings in _site.yml override them. If you wish to change the setting of one particular notebook file, as opposed to every file in your project, you can set it with workflowr::wflow_html(). For example, if you want to enable folding of code chunks and disable the table of contents for only this file, you could use the following YAML header.

---
title: "Using R Notebook with workflowr"
output:
  html_notebook: default
  workflowr::wflow_html:
    toc: false
    code_folding: show
---

How should I pronounce and spell workflowr?

You can say “workflowr + er” or “workflowr + R”, whichever is more natural to you.

Workflowr should be capitalized at the beginning of a sentence, but otherwise the lowercase workflowr should be the preferred option.