Publishing websites with RStudio and GitHub

Starting Point

To organize the process of learning new concepts and terminology we start with GitHub Pages Help. There is a difference between producing a website for a user or organization, and the a website for a specific project. One can use an Automatic Page Generator, but from my understanding so far the limitations of this approach might be substantial. Please report on the use of this technique in the comments and I’ll update this section.

A. Setting up Jekyll pipeline

To set up Jekyll publishing you will need (I)Ruby language, (II)dependency manager Bundler and (III)atomatic page generator Jekyll :

B. Preparing for publishing

Jekyll will take the collection of files and folders in the “gh-pages” of your repository and assemble a static website out of them.

Here I demonstrate how to replicate verbatim the styles and settings from the official website of rmarkdown.

1. Go to the gh-pages branch of the rmarkdown GitHub repository (you may need to clone it to your machine if you haven’t done so already)

2. Into the root of your project’s gh-pages branch, copy the following:
   • folder libs containing style libraries
   • folder include containing header (menu) and footer (comments) for the website
   • file Makefile - clarify the function
   • file _output.yaml - defining the common output options for .Rmd files
     In the future, these styles can be modified to fit the needs of the project.
   • Alternative to steps III.a - III.c, you can copy an existing file “Gemfile”

NOTE: I’m still working on editing the styles of the site. Two routes are possibles:
- Route One : edit the min.js style libraries directly - Route Two : find a better fitting Bootstrap templates.
These routes need researching before recommendation for reproduction. Please report your tests in the comments.

C. Producing the website

At this point the website is a collection of .Rmd files stored in a single repository. Their output attributes are shared and controlled by output.yaml in the root. To produce the website execute the following steps:

1. Run “produceReports.R” scripts that prints HTML from all .Rdm files. For example:

path_index<- base::file.path("./index.Rmd")
path_ghPages<- base::file.path("./gh-pages-setup.Rmd")
path_workStation<- base::file.path("./work-station-setup.Rmd")

buildthese<- c(path_index, path_ghPages,path_workStation)

for( pathRmd in buildthese ) {
  rmarkdown::render(input = pathRmd,output_format=c("html_document"), clean=TRUE)
}

2. Open command line from the repository’s root and execute

   bundle exec jekyll serve

   This will assemble the website and deploy it to the local host. Examine it at

   localhost:4000

   Alternatively, you can add this line at the end of “produceReports.R” script

   # base::system("bundle exec jekyll build") 
   # or
   # base::system("bundle exec jekyll serve")

   However, I’m not sure, whether the working directory is passed to jekyll or not. Needs testing.

3. Commit and sync the changes in the gh-pages branch. The website should become availible at

   username.github.io/projectname

   or a custom address.

To change the website one must repeat these steps after introducing changes in the initial .Rmd files

D. Connecting to Disqus

1. Register an account with Disqus if you haven’t already.

2. When logged in go to Settings got Admin area

3. Click on the drop-down button and select “Add new site”

4. Enter the names of your blog, that will be hosted on disqus servers.

5. After completing the registration the promt will take you to the page containing code snippets you have to add to your website to enable the comments

• copy the snippets into appropriate places in the file ./include/after_body.html

6. Re-run the steps 1-3 from the previous subsection. The comments should be enabled now.