---
title: "Frequently asked questions"
subtitle: "workflowr version `r utils::packageVersion('workflowr')`"
author: "John Blischak"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Frequently asked questions}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## 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://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](wflow-01-getting-started.html), 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][gh-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][gh-status] 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][gh-troubleshooting].

## Can I make my workflowr website private?

Yes. While it it is **not** possible to make a [GitHub Pages][gh-pages] site
private (the default setup described in the ["Getting Started"
vignette][vig-getting-started]), 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:

* You can host a private site on [GitLab Pages][gl-pages] and grant access to
collaborators. All they need is a GitLab.com account (and they can use a social
account, e.g. Twitter, to login to GitLab.com) - [Deploy your site with GitLab
Pages][vig-gitlab]
* You can use [Beaker Browser][beaker] to securely self-host your site and share
the link with collaborators - [Deploy your site with Beaker
Browser][deploy-beaker]
* You can deploy a password-protected site using [Amazon Web Services][aws]
(requires familiarity with cloud technologies) - [Deploy your site with
AWS][deploy-aws]

To see all the currently documented deployment options, see the vignette
[Alternative strategies for deploying workflowr websites][vig-deploy].

## How should I manage large data files in a workflowr project?

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][vig-data] for various options
for versioning the large data files used in your workflowr project.

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

1. 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")
    ```
1. Move the image file(s) to `docs/assets/`
1. 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)
    ```
    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)`
1. Run `wflow_build()` to confirm the external image file(s) are properly
displayed
1. 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 ...")
    ```
1. 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](https://imgur.com/), [Figshare](https://figshare.com/), 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.

## How can I save a figure in a vector graphics format (e.g. PDF)?

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'}`r ''`
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](https://yihui.org/knitr/options/) globally:

````
```{r setup, dev='svg'}`r ''`
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')}`r ''`
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}`r ''`
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}`r ''`
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}`r ''`
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)
```
````

## Can I include Shiny apps in my website?

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][shiny-external-resources] than the standard for an
Rmd-based website.

[shiny-external-resources]: https://rmarkdown.rstudio.com/authoring_shiny_prerendered.html#external_resources

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](https://www.shinyapps.io/), and then embed it directly into your
document by calling `knitr::include_app()` inside a code chunk, as shown below:

````markdown
`r ''````{r shiny-app}
knitr::include_app("https://<user-name>.shinyapps.io/<app-name>/")
```
````

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.

## 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](wflow-02-customization.html) provides
some ideas that are simple to implement. Check out the documentation for
[rmarkdown][] and [Twitter Bootstrap][Bootstrap] for inspiration.

## How can I suppress the workflowr report?

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: TRUE
```

And 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: TRUE
```

## 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][issues] and
provide a small reproducible example.

## How should I install packages to use with a workflowr project?

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:

1. Always restart your R session after installing new packages
(Ctrl/Command+Shift+F10 in RStudio)
1. Open R from a directory that is not a workflowr project when installing new
packages
1. Delete `.Rprofile` with `wflow_remove(".Rprofile")` and manually load
workflowr with `library(workflowr)` every time you start a new R session


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

Yes! 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.

### Working directory

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.

### PDF

To convert a single analysis to PDF, use `pdf_document()`. Note that this
requires a functional LaTeX setup.

```{r render-single-page-pdf, eval=FALSE}
library("rmarkdown")
# Create analysis/file.pdf
render("analysis/file.Rmd", pdf_document(), knit_root_dir = "..")
```

### HTML

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()`.

```{r render-single-page-html-1, eval=FALSE}
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.

```{r render-single-page-html-2, eval=FALSE}
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.

```{r render-single-page-html-3, eval=FALSE}
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):

```{r render-single-page-html-4, eval=FALSE}
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.

```{r render-single-page-html-5, eval=FALSE}
# use the workflowr::wflow_html settings in analysis/_site.yml
render("analysis/file.Rmd", knit_root_dir = "..")
```

### RStudio Knit button

Ideally you should also be able to use the RStudio Knit button to conveniently
create the standalone HTML or PDF files. For example, you could update the
YAML header to have multiple output formats, and then choose the output format
that RStudio should create. The workflowr functions like `wflow_build()` will
ignore these other output formats because they use the output format defined in
`analysis/_site.yml`.

```
---
output:
  pdf_document: default
  html_document_base: default
  workflowr::wflow_html: default
---
```

However, just like when calling `render()` directly, you'll need to be careful
about the working directory. To execute the code in the project directory, you
can manually set the Knit Directory to "Project Directory" (the default is
"Document Directory" to match the default behavior of R Markdown files).

Lastly, the RStudio Knit button is somewhat finicky when custom output formats
are included (e.g. workflowr, bookdown). If you are having trouble getting it
to display the output format you want as an option, try knitting it to the current
format. That should update the menu to include all the options you've written in
the YAML header. See [Issue #261][issue-261] for more details.

[issue-261]: https://github.com/workflowr/workflowr/issues/261

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

````markdown
`r ''````{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
---
```

## Can I use a Git hosting service that uses the HTTP protocol?

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**

1. Configure the remote with `wflow_git_remote()` and `protocol = "ssh"`
1. You can use `wflow_git_push()` and `wflow_git_pull()`
1. 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**

1. You can't use `wflow_git_remote()`. Instead use either
    a. `git2r::remote_add()` in R:

        ```
        git2r::remote_add(name = "origin", url = "https://custom-site/<username>/<reponame>.git")
        ```
    a. `git remote add origin` in the terminal:

        ```
        git remote add origin https://custom-site/<username>/<reponame>.git
        ```
1. You cannot use `wflow_git_push()` and `wflow_git_pull()`. Instead run
`git push` and `git pull` in the terminal
1. The embedded links to past versions of the files will be correct because they
will be based off of your remote URL

## How should I pronounce and spell workflowr?

There are multiple options for pronouncing workflowr:

1. workflow + er
1. workflow + R
1. work + flower

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.

[aws]: https://aws.amazon.com/s3/
[beaker]: https://beakerbrowser.com/
[Bootstrap]: https://getbootstrap.com/
[deploy-aws]: wflow-08-deploy.html#amazon-s3-password-protected
[deploy-beaker]: wflow-08-deploy.html#beaker-browser-secure-sharing
[gh-pages]: https://pages.github.com/
[gh-status]: https://www.githubstatus.com/
[gh-troubleshooting]: https://docs.github.com/articles/troubleshooting-github-pages-builds
[gl-pages]: https://docs.gitlab.com/ce/user/project/pages/index.html
[issues]: https://github.com/workflowr/workflowr/issues
[rmarkdown]: https://rmarkdown.rstudio.com/
[vig-data]: wflow-10-data.html
[vig-deploy]: wflow-08-deploy.html
[vig-getting-started]: wflow-01-getting-started.html
[vig-gitlab]: wflow-06-gitlab.html