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
masterbranch 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.
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.
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:
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")docs/assets/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.:
Alternatively, you could use knitr::include_graphics() inside of an R code chunk, which will automatically center the image and also follow the knitr chunk options out.width and out.height:
knitr::include_graphics("assets/external.png")wflow_build() to confirm the external image file(s) are properly displayedUse 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 ...")Run wflow_publish() on the R Markdown file that contains the external image file(s)
The default file format is PNG. This is ideal for displaying figure files on a web page. However, you might need to import a figure into a vector graphics editor (e.g. Illustrator, Inkscape) for final editing for a manuscript. There are multiple options for achieving this.
One option is to switch to the file format SVG. It is a vector graphics format that is also well supported by web browsers. The code chunk below saves the figure file as an SVG:
```{r plot-for-paper, dev='svg'}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
```To apply this to every figure file in a particular document, you can create a “setup” chunk at the beginning of the document that sets the knitr chunk option globally:
```{r setup, dev='svg'}
knitr::opts_chunk$set(dev = 'svg')
```Another option is to simultaneously create a PNG for display in the web page and a PDF for further editing. The example code below saves both a PNG and PDF version of the figure, but inserts the PNG into the web page:
```{r plot-for-paper, dev=c('png', 'pdf')}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
```The main advantage of the above approaches is that the figure files are still saved in an organized fashion (i.e. the file path is still something like docs/figure/file.Rmd/chunk-name.ext). Furthermore, wflow_publish() will automatically version the figure files regardless of the file extension.
A similar option to the one above is to have two separate code chunks. The advantage of this more verbose option is that you can specify different chunk names (and thus different filenames) and also set different fig.width and fig.height for the website and paper versions. By setting include=FALSE for the second chunk, neither the code nor the PDF figure file is displayed in the web page.
```{r plot-for-paper}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
``````{r figure1A, include=FALSE, dev='pdf', fig.height=3, fig.width=9}
p
```However, for the most control, you can always save the figure manually, e.g. using ggsave(). For example, the example chunk below creates a 10x10 inch PNG file that is automatically versioned by workflowr, but also uses ggsave() to save a 5x5 inch PDF file in the subdirectory paper/ (which would need to be manually committed by the user, e.g. with wflow_git_commit()):
```{r plot-for-paper, fig.width=10, fig.height=10}
library(ggplot2)
data(mtcars)
p <- ggplot(mtcars, aes(x = mpg, y = disp)) + geom_point()
p
ggsave("paper/plot-to-edit.pdf", width = 5, height = 5)
```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.
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.
To suppress the insertion of the workflowr report for all of the files in your project, activate the option suppress_report in the _workflowr.yml file by adding the following line:
suppress_report: TRUEAnd then republishing your project:
wflow_publish("_workflowr.yml", republish = TRUE)To suppress the workflowr report only for a specific file, add the following lines to its YAML header:
workflowr:
suppress_report: TRUEYes. Please see these instructions for deploying a workflowr project with password-protection using Amazon S3.
When you start a new workflowr project with wflow_start(), it automatically creates a local .Rprofile file that only affects your R session when you run R from within your workflowr project. This is why you see the following lines each time you open R:
Loading .Rprofile for the current workflowr project
This is workflowr version 1.3.0
Run ?workflowr for help getting started
>This is intended to be a convenience so that you don’t have to type library(workflowr) every time you return to your project (or restart your R session). However, the downside is that this has the potential to cause problems when you install new packages. If you attempt to install one of the packages that workflowr depends on, or if you attempt to install a package that then updates one of these dependencies, this may cause an error. For example, here is a typical error caused by updating git2r when the workflowr package is loaded:
Error: package or namespace load failed for ‘git2r’ in get(method, envir = home):
lazy-load database '/usr/local/lib/R/site-library/git2r/R/git2r.rdb' is corrupt
In addition: Warning message:
In get(method, envir = home) : internal error -3 in R_decompress1The short term solution is to restart your current R session, which should fix everything. In the long term, if you start to get this type of error often, you can try one of the following strategies:
.Rprofile with wflow_remove(".Rprofile") and manually load workflowr with library(workflowr) every time you start a new R sessionYes! 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:
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: consoleSecond, 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:
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().
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
---There are multiple options for pronouncing workflowr:
I (John) started primarily saying “workflow + er” but have more recently transitioned to saying “workflow + R” more often. You can choose whichever is most natural to you.
Workflowr should be capitalized at the beginning of a sentence, but otherwise the lowercase workflowr should be the preferred option.