Frequently asked questions

workflowr version 1.2.0

John Blischak


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:

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/:

  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.:

  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 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 pacakges 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 occassionally 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.

# 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.

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.