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
documentation for the available options), and 2) configure the workflowr
reproducibility features (typically specified in a file named
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.
Arguments passed to
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
websites). For example, to use the theme "cosmo" and add a table of contents
to every webpage, you would add the following to
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:
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.
wflow_html also implements the workflowr reproducibility features. For
example, it automatically sets a seed with
the current code version (i.e. Git commit ID); runs
at the end of the document; and inserts links to past versions of the file
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
workflowr:). These options (along with their default values) are
The directory where code inside an R Markdown file is
executed; this ultimately sets argument
render. By default,
knit_root_dir in the file
_workflowr.yml to be the path
".". This path is a
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
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.
knit_root_dir: "../data" would execute the code in the
seed argument in the call to
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
The function that is run to record the session
information. The default is
The URL of the remote repository for creating links to past
results. If unspecified, the URL is guessed from the "git remote" settings
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
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
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
# Execute code in project directory
# Set a custom seed
# Use sessioninfo package to generate the session information.
# Use this URL when inserting links to past results.
And here is an example of a YAML header inside an R Markdown file with the same exact custom settings as above:
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.