Convert to a workflowr HTML document

Source: R/wflow_html.R

Workflowr custom format for converting from R Markdown to an HTML document. wflow_html has two distinct functionalities: 1) configure the formatting of the HTML by extending html_document (see the RStudio documentation for the available options), and 2) configure the workflowr reproducibility features (typically specified in a file named _workflowr.yml). wflow_html is intended to be used to generate webpages for a workflowr website, but it can also be used outside a workflowr project to implement reproducibility features for single R Markdown documents.

wflow_html(...)

Arguments

...

Arguments passed to html_document.

Value

An output_format object to pass to render.

HTML formatting

wflow_html extends html_document. To set default formatting options to be shared across all of your HTML files, set them in the file analysis/_site.yml. This special file can also be used to configure other aspects of the website like the navigation bar (for more details see the documentation on R Markdown websites). For example, to use the theme "cosmo" and add a table of contents to every webpage, you would add the following to analysis/_site.yml:


output:
  workflowr::wflow_html:
    toc: true
    theme: cosmo

Formatting options can also be set for a specific file, which will override the default options set in analysis/_site.yml. For example, to remove the table of contents from one specific file, you would add the following to the YAML header of that file:


output:
  workflowr::wflow_html:
    toc: false

However, this will preserve any of the other shared options (e.g. the theme in the above example). If you are not overriding any of the shared options, it is not necessary to specify wflow_html in the YAML header of your workflowr R Markdown files.

Reproducibility features

wflow_html also implements the workflowr reproducibility features. For example, it automatically sets a seed with set.seed; inserts the current code version (i.e. Git commit ID); runs sessionInfo at the end of the document; and inserts links to past versions of the file and figures.

These reproducibility options are not passed directly as arguments to wflow_html. Instead these options are specified in _workflowr.yml or in the YAML header of an R Markdown file (using the field workflowr:). These options (along with their default values) are as follows:

knit_root_dir

The directory where code inside an R Markdown file is executed; this ultimately sets argument knit_root_dir in render. By default, wflow_start sets knit_root_dir in the file _workflowr.yml to be the path ".". This path is a relative path from the location of _workflowr.yml to the directory for the code to be executed. The path "." is shorthand for "current working directory", and thus code is executed in the root of the workflowr project. You can change this to be a relative path to any subdirectory of your project. Also, if you were to delete this line from _workflowr.yml, then this would cause the code to be executed from the same directory in which the R Markdown files are located (i.e. analysis/ in the default workflowr setup).

It is also possible (though in general not recommended) to configure the knit_root_dir to apply to only one of the R Markdown files by specifying it in the YAML header of that particular file. In this case, the supplied path is interpreted as relative to the R Markdown file itself. Thus knit_root_dir: "../data" would execute the code in the subdirectory data/.

seed

The seed argument in the call to set.seed, which is added to the beginning of an R Markdown file. In wflow_start, this is set to the date using the format YYYYMMDD. If no seed is specified, the default is 12345.

sessioninfo

The function that is run to record the session information. The default is "sessionInfo()".

github

The URL of the remote repository for creating links to past results. If unspecified, the URL is guessed from the "git remote" settings (see wflow_git_remote). Specifying this setting inside _workflowr.yml is especially helpful if multiple users are collaborating on a project since it ensures that everyone generates the same URLs.

suppress_report

By default a workflowr report is inserted at the top of every HTML file containing useful summaries of the reproducibility features and links to past versions of the analysis. To suppress this report, set suppress_report to TRUE

.

In the default workflowr setup, the file _workflowr.yml is located in the root of the project. For most users it is best to leave it there, but if you are interested in experimenting with the directory layout, the _workflowr.yml file can be located in the same directory as the R Markdown files or in any directory upstream of that directory.

Here is an example of a customized _workflowr.yml file:


# Execute code in project directory
knit_root_dir: "."
# Set a custom seed
seed: 4815162342
# Use sessioninfo package to generate the session information.
sessioninfo: "sessioninfo::session_info()"
# Use this URL when inserting links to past results.
github: https://github.com/repoowner/mainrepo

And here is an example of a YAML header inside an R Markdown file with the same exact custom settings as above:


---
title: "About"
output:
  workflowr::wflow_html:
    toc: false
workflowr:
  knit_root_dir: ".."
  seed: 4815162342
  sessioninfo: "sessioninfo::session_info()"
  github: https://github.com/repoowner/mainrepo
---

Note that the path passed to knit_root_dir changed to ".." because it is relative to the R Markdown file instead of _workflowr.yml. Both have the effect of having the code executed in the root of the workflowr project.