This repository is a skeleton for a reproducible R pipeline that allows you to create and publish analyses online hosted through Github Pages. It works by knitting the Rmd files in the notebooks directory into the export directory to create a static HTML site which can be hosted from the repository containing the original work. This is nice because it reduces the number of repositories related to a single project and allows you to keep all of your work in one place.

How To Use It

To use this pipeline, there are a few simple steps.

  1. Copy the contents of this repo locally. Do not edit any of the files in the utils directory.
  2. Put any analysis notebooks in the notebooks directory. Make sure your filenames follow the naming scheme. Make sure each notebook includes the JavaScript to generate the menus.
  3. Create a homepage for your project.
  4. Run the file utils/export.R. This will generate the necessary JavaScript files for the page menus and knit each Rmd file in the notebooks directory. All output HTML files should appear in the export directory.
  5. Push to Github and you’re done!

Naming Scheme

Files in the notebooks directory need to follow a particular naming scheme so that the R scripts which knit the notebooks order them correctly in the menu. This scheme begins each file with a 2-digit number indicating the order (first is 01, second 02, etc.). Each word in the notebook title (what you want displayed in the menu) should follow that number with hyphens in place of spaces.

For example, if the fifth notebook was titled “Principal Component Analysis with Scree Plot”, then the filename would be 05-principal-component-analysis-with-scree-plot.Rmd. The utilities function will automatically capitalize all words in the title.

Project Homepage

The homepage for your project will also be located in this folder but it will be named index.Rmd (not following the naming scheme). This is important because Github pages requires an index.html file in the root directory for the project as the homepage.

A sample structure, from the Github repo for this project, is given below.

| notebooks
  | 01-sample-page.Rmd
  | index.Rmd

JavaScript Menus

The menus in this project are generated through R writing a JavaScript file which is executed in the HTML output files. In order to include the menu on each page, the Rmd file needs to include an HTML script tag so that the menu is loaded with in the knitted document.

For all notebooks except the index notebook, include the HTML below at the top of the notebook (directly below the YAML header):

<script type="text/javascript" src="../utils/menu.js"></script>

The utils/generate-menu.R script, executed in the utils/export.R script, creates the JS file referenced above, along with the menu for the index page.

For the index notebook, the HTML script tag is a bit different:

<script type="text/javascript" src="../utils/index-menu.js"></script>

This is because the index.html file is in a different directory from the knitted HTML files and so the links to other pages are different.


These are some things I’ve noticed that make the output look nicer when using this workflow.