In jdblischak/workflowrBeta: A workflow template for creating a research website

library("knitr")
opts_chunk$set(eval = FALSE)

There are many ways to customize your research website. Below are some common options.

Adding project details

workflowr automatically creates many files when the project is first started. As a first step for customizing your site, add the following information:

• Briefly describe your project in analysis/index.Rmd
• Share details about yourself in analysis/about.Rmd
• Copy the text for a license into LICENSE and state the name of the license in analysis/license.Rmd. See A Quick Guide to Software Licensing for the Scientist-Programmer by Morin et al., 2012 for advice. If you're ambivalent, the MIT license is a standard choice
• Decide how authors should attribute your work by providing a citation in CITATION

Changing the theme

The theme is defined in the file analysis/_site.yml. The default is cosmo, but the rmarkdown package accepts multiple Bootstrap themes. These are listed in the rmarkdown documentation. Go to bootswatch.com to compare the bootstrap themes. When typing the theme, make sure it is all lowercase (e.g. spacelab, united, etc.).

If you are using RStudio (version > 1.0), you can quickly see how the theme looks for one of your files. Open one of your R Markdown files, click Knit so that it appears in the Viewer tab, and then edit analysis/_site.yml. Every time you save an edit to the file, it will automatically re-render the R Markdown file and update the result in the Viewer (thus you'll want to use a quick-running file like index.Rmd when testing aesthetic changes).

Once you have chosen a theme, update the website by running the following:

wflow_publish("analysis/_site.yml", "Change the theme", republish = TRUE)

This commits analysis/_site.yml, re-builds every previously published HTML file using the new theme, and commits all the republished HTML pages.

Customize the navigation bar

The navigation bar appears on the top of each page. By default it includes links to index.html (Home), about.html (About), license.html (License), and the workflowr repository (the GitHub icon). This is all specified in analysis/_site.yml. To start, replace the URL to the workflowr GitHub repository with the URL to your GitHub repository.

If you have other important pages, you can add them as well. For example, to add the text "The main result" which links to main-result.html, you would add the following:

    - text: "The main result"
      href: main-result.html

You can also create a drop-down menu from the navigation bar. See the rmarkdown documentation for instructions.

Similar to changing the theme above, you will need to re-render each page of the website (the navbar is embedded within each individual HTML file). Thus you could run the same command as above:

wflow_publish("analysis/_site.yml", "Add main result page to navbar",
              republish = TRUE)

Add a links page

To make it easy to navigate to the pages of your website, you can manually add links either to analysis/index.Rmd or to the navigation bar defined in analysis/_site.yml. This can become tedious as the project grows to many files. To create a file called analysis/results.Rmd that contains links to each analysis file, run the workflowr function create_links_page(). By default it sorts the files by their filename, but there are other options (see ?create_links_page).

Next add this page to the navigation bar in analysis/_site.yml to make it easily accessible.

    - text: "Results"
      href: results.html

Lastly, since the navigation bar was changed, re-build the website using the following command:

wflow_publish(c("analysis/_site.yml", "analysis/results.Rmd"),
              "Create links page and add to navbar",
              republish = TRUE)

Future updates of results.Rmd will not require re-building the entire website since it is an independent page (as opposed to the navigation bar).

Customize the footer

By default your workflowr website has the footer "This R Markdown site was created with workflowr" added to the end of each page. This is specified in the file analysis/include/footer.html and this file is specified in analysis/_site.yml. To remove the footer entirely, delete the following lines:

    include:
      after_body: include/footer.html

To change the text that appears, directly edit the HTML file. Including formatting (e.g. bold, hyperlink, etc.) requires knowing HTML.

This file is also how you can enable disqus comments for your website pages. To enable comments, follow these steps:

1. Start a disqus account
2. Add your disqus shortname to footer.html
3. Uncomment the disqus code in footer.html

To change the footer for every page of the website, run the following:

wflow_publish("analysis/include/footer.html", "Customize the footer",
              republish = TRUE)

Setup SSH keys

Using the https protocol to communicate with GitHub is tedious because it requires entering your GitHub username and password. Using SSH keys for authentication removes the password requirement. Follow these GitHub instructions for creating SSH keys and linking them to your GitHub account. You'll need to create separate SSH keys and link them each to GitHub for each machine where you clone your Git repository.

After you create your SSH keys and add them to your GitHub account, you'll need to instruct your local Git repository to use the SSH protocol. For a hypothetical GitHub username of "myname" and GitHub repository of "myproject", you would change the remote "origin" (the default name by convention) using the function wflow_remotes():

wflow_remotes(remote = "origin", user = "myname", repo = "myproject",
              protocol = "ssh", action = "set_url")

Alternatively you could update the remote URL using Git directly in the shell. See this GitHub documentation on changing a remote URL for instructions.

jdblischak/workflowrBeta documentation built on May 17, 2019, 7:28 p.m.