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://docs.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 website githubstatus.com for the most up-to-date reports directly 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.
Yes. While it it is not possible to make a GitHub Pages site private (the default setup described in the “Getting Started” vignette), there are various other hosting platforms that provide access control. Below are the currently documented options, in order of least to most amount of technical setup required:
To see all the currently documented deployment options, see the vignette Alternative strategies for deploying workflowr websites.
Tracking the changes to your project’s large data files is critical for reproducibility. Unfortunately Git, which is the version control software used by workflowr, was designed to version small files containing code. See the vignette Using large data files with workflowr for various options for versioning the large data files used in your workflowr project.
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 the
steps below. The instructions refer to docs/ for the
website directory since this is the default. If you are not using GitHub
Pages to host the website, you may need to change this. For example, if
you are hosting with GitLab Pages, replace docs/ with
public/.
Inside the website directory, create a subdirectory named
assets to include any file that should be part of the
website but is not created by one of the R Markdown files in
analysis/:
dir.create("docs/assets")Move the image file(s) to 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", error = FALSE)Note that the image will not be previewed in the R Markdown file
inside of RStudio because it is in a different directory than the R
Markdown file. You have to set error = FALSE because the
function throws an error if it can’t find the file. This breaks the
workflowr setup, since the file path only exists once the HTML file is
moved to docs/. If you’d like to disable knitr from
throwing this error for all the code in your project, add the following
line to the .Rprofile in your project:
options(knitr.graphics.error = FALSE)
Run wflow_build() to confirm the external image
file(s) are properly displayed
Use wflow_git_commit() to commit the file(s) to the
Git repo (so that they get pushed to the remote repository, e.g. on
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)
Another option is to first upload the image, e.g. to Imgur, Figshare, another GitHub repository, etc. Then you can link directly to the image in your Rmd file using the absolute URL. This has the added advantage that the image will automatically display in the Rmd file as you edit it in RStudio. The main disadvantage is that the image isn’t in the same location as the rest of your project files.
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)
```Yes, but not directly. You cannot directly embed the Shiny app into
the Rmd file using runtime: shiny_prerendered for two
reasons. First, workflowr creates a static website, and the free
deployment options (e.g. GitHub Pages), only provide static web hosting.
Shiny apps require a dynamic website because they need to call a server
to run the R code. Second, even if you setup your own web server, the
supporting files (e.g. CSS/JS) for a Shiny app have to be in a different
location than the standard for an Rmd-based website.
However, there is still a good option for embedding the Shiny app
directly into the web page. You can upload your Shiny app to shinyapps.io, and then embed it
directly into your document by calling knitr::include_app()
inside a code chunk, as shown below:
Using this method, the R code for the Shiny app is executed on the servers at shinyapps.io, but your readers are able to explore the app without leaving your 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.
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: TRUEWhen 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! You can create a single HTML or PDF file to distribute an
isolated analysis from your project by directly running the rmarkdown function
render(). The main limitation is that any links to other
pages will no longer be functional.
You will need to be careful with the working directory in which the
code is executed. By default, code in R Markdown documents are executed
in the same directory as the file. This is cumbersome, so the default
behavior of workflowr is to set the working directory to the root
project directory for convenience. To get around this, you can pass
knit_root_dir = ".." or
knit_root_dir = normalizePath(".") to
render(), which both have the effect of running the code in
the project root. If you have configured your workflowr project to
execute the files in analysis/, then you don’t have to
worry about this.
To convert a single analysis to PDF, use pdf_document().
Note that this requires a functional LaTeX setup.
Rendering a single HTML page is slightly more complex because
html_document() always includes the navigation bar. If you
don’t mind the non-functional navbar at the top of the document, you can
simply use html_document().
library("rmarkdown")
# Create analysis/file.html, includes navigation bar
render("analysis/file.Rmd", html_document(), knit_root_dir = "..")The standalone file will be saved as analysis/file.html
unless you specify a different name via the argument
output_file.
To create a very simple HTML file, you can instead use
html_document_base(). This eliminates the navbar, but it
may also remove some of the advanced stylistic features of
html_document() that you rely on.
library("rmarkdown")
# Create analysis/file.html, no navigation bar nor advanced features
render("analysis/file.Rmd", html_document_base(), knit_root_dir = "..")If you are determined to have a full-featured standalone HTML file
without the navigation bar, you can temporarily rename the
_site.yml file, which prevents html_document()
from including the navbar.
library("rmarkdown")
# Temporarily rename _site.yml
file.rename("analysis/_site.yml", "analysis/_site.yml_tmp")
# Create analysis/file.html, no navigation bar
render("analysis/file.Rmd", html_document(), knit_root_dir = "..")
# Restore _site.yml
file.rename("analysis/_site.yml_tmp", "analysis/_site.yml")If you’d like your standalone HTML file to have a similar appearance
to your workflowr website, you can pass the style arguments directly to
html_document() so that the theme is similar (copy from
your project’s analysis/_site.yml, below are the default
values for a new workflowr project):
render("analysis/file.Rmd",
html_document(toc = TRUE, toc_float = TRUE, theme = "cosmo", highlight = "textmate"),
knit_root_dir = "..",
output_file = "standalone.html")Alternatively, if you’d prefer to keep the workflowr report and other
workflowr-specific features in the standalone document, don’t use
output_file, as this will cause workflowr to insert the
warning
The custom `fig.path` you set was ignored by workflowr if
the analysis contains any figures. Instead, omit both
html_document() and output_file. The
standalone HTML file will be saved in analysis/ (the
standard, non-standalone HTML files are always moved to
docs/), and you can move/rename it after it has
rendered.
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.
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
---Workflowr works best with Git hosting services that use the HTTPS protocol. However, with some minimal upfront configuration, it is possible to use the HTTP protocol.
The configuration differs depending on whether you are authenticating with SSH keys or username/password.
SSH keys
Configure the remote with wflow_git_remote() and
protocol = "ssh"
You can use wflow_git_push() and
wflow_git_pull()
For the embedded links to past versions of the files to be
correct, you need to manually include the URL to the project in
_workflowr.yml (for historical reasons, this variable is
named github)
github: https://custom-site.com/<username>/<reponame>Username/Password
wflow_git_remote(). Instead use either
git2r::remote_add() in R:
git2r::remote_add(name = "origin", url = "https://custom-site/<username>/<reponame>.git")git remote add origin in the terminal:
git remote add origin https://custom-site/<username>/<reponame>.gitwflow_git_push() and
wflow_git_pull(). Instead run git push and
git pull in the terminalThere 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.