In grunwaldlab/quiltr: Automated website creation from scattered HTML

Introduction

Quiltr projects work well with git version control since all of the input and output is in the form of text files. One perk of using git is GitHub which offers unlimited free public repository hosting. Repositories on GitHub can have an associated website at GitHub Pages by adding a "gh-pages" branch containing the website source. For example, this website lives in the "gh-pages" branch of the Quiltr repository. To make it easy to host Quiltr output on GitHub Pages, there is a wrapper function called make_gh_website that will build a website using quilt and put its output in the "gh-pages" branch of a git repository.

Summary

The make_gh_website function is used in the same way as quilt and accepts all of its arguments. This makes it easy to develop and test websites using quilt and then use make_gh_website with the same parameters to put the website online when it is ready. The make_gh_website function will make automated commits of automatically produced HTML, so to avoid inflating the repository, make_gh_website should only be used to update websites, rather than for testing. A typical work flow would be:

1. Make new git repository at GitHub
2. Clone (i.e. download) the new repository to your computer
3. Make an R project out of the repository using RStudio
4. Add a configuration file to govern website build
5. Add/change Rmarkdown files.
6. Preview website using quilt() in the repository directory
7. Repeat steps 5 and 6 until the site is ready to go online
8. Run make_gh_website() to make it available on GitHub Pages.

Workflow

This is just one example of many possible workflows, chosen for ease use. For the purposes of demonstration, I will start by explaining how to make a new git repository on GitHub. If you already have a git repository on GitHub, you can use that and skip to the sections on adding a configuration file and HTML content.

Ingredients

To follow the example workflow below, you will need:

• Quiltr
• git
• RStudio
• A GitHub account

1) Making a new git repository

To start a new repository, go to GitHub and log in. Click on the + sign on the top right, next to your user name, and choose "New Repository". Choose a name for the repository (this will be the directory name on you computer) and select to "Initialize this repository with a README". Initializing with a README simplifies the process of getting a copy on your computer.

2) Downloading the new repository

The repository now exists on GitHub, but we need a copy of it on a computer to do anything to it. Git can be used to download a copy, but it needs a SSH clone URL. This can be found on the repository's GitHub page at the bottom the menu on the right. Open up a terminal (aka command line prompt) and change directories to the place you want to download the repository to. Enter git clone [e-mail]:user/repo.git, where [e-mail]:user/repo.git is the SSH clone URL you copied. This command should create a new directory in the current working directory with the same name as your repository. If this is the first time using GitHub on your computer, you will need to set up a SSH key pair.

3) Making an R project

It is not necessary to use RStudio or make the repository into an R project, but both add enough convenience to make doing it worthwhile. Start RStudio and select "New Project..." from the dropdown menu location at the top right. In the window that pops up, select "Existing Directory" and specify the repository directory. This will add a few files to the repository and change the current working directory to the repository (You can see this to the right of the "Console" header). One of the files made is a "repo.Rproj" file (where "repo" is your repository name), which can be used to open the project again in RStudio.

4) Adding a website configuration file

Although not necessary, website build configuration files are useful for storing quilt parameters in the source of the website. This allows quilt to be run with no options when in the project directory (where RStudio always starts when opening R projects). The values of quilt options are important when deciding file names and directory structure of file content, but for demonstration, lets only specify one option and not worry about it too much. Make a new text file (upper left drop down menu in RStudio) named "quilt_config.yml" and save the following content in it:

theme: spacelab

To see what effect this has and other available options, see the documentation on quilt options.

5) Adding content

Now we can finally start adding the content of the soon-to-be website. See the introduction section for how file and directory names affect where the content is displayed on the website. In this example, we will RMarkdown (".Rmd") files for content. However, many other file types can be used as well.

Make a new Rmd file using the drop down menu at the top left. The default settings are fine for our purposes, but any configuration that outputs HTML should work. To make this appear on the home page, save the Rmd under root of the target directory.

By default, the quilt function ignores the file name, but uses directory names; in this case, the file is not in a sub-directory, so the content is displayed on the home page. Add other Rmd files in sub-directories to place more content in other parts of the website. For example, the file "notes/part_1/a_random_note.Rmd" would be displayed under the notes > part 1 menu location on the website.

6) Previewing the webpage

To build a webpage from the Rmd files in the repository directory, simply enter quilt() in the R console window. By default, the website will be saved to a temporary directory and displayed in the RStudio "Viewer" window. Make any desired changes to the Rmd content and repeat until satisfied.

7) Publishing the site on GitHub Pages

When the site is ready to go online, enter make_gh_website(push = TRUE) in the R console. If everything worked, the site should be viewable online at the URL returned by the function.

grunwaldlab/quiltr documentation built on May 17, 2019, 8:40 a.m.