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:
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
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
wflow_build()to confirm the external image file(s) are properly displayed
wflow_git_commit() to commit the file(s) to the Git repo (so that they get pushed to GitHub):
wflow_publish() on the R Markdown file that contains the external image file(s)
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.
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_decompress1
The 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:
wflow_remove(".Rprofile")and manually load workflowr with
library(workflowr)every time you start a new R session
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
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_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
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.
If you change the value of
_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
_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
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_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.