At the end of discussion on how to produce HTML documents from .Rmd the official page of the rmarkdown package mentions that entire website can be produced using R Markdown and the described methodology.

Creating a website similar to rmarkdown.rstudio.com can be accomplished using a combination of GitHub Pages and Jekyll (static website generator). The current guide narrates the process of publishing a statitic, blog-aware website from a GitHub repository containing multiple .html files, printed from .Rmd files and united by common attributes in the **_output.yaml** options file.

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 :

(I) Ruby

  1. Install Ruby for Windows using RubyInstaller
  • I used version: Ruby 1.9.3-p545
  • check Add Ruby executables to your PATH box, I checked all
  1. Download Developmental Kit (DevKit) from the Ruby’s [download]http://rubyinstaller.org/downloads/) page
  • I used version: tdm-32-4.5.2
  • Unpack zip into folder DevKit inside the folder where Ruby was installed.
  • Follow the guide to properly instlall the kit.

    In brief:
    1. Open the folder wher DevKit was unzipped

        cd c:\Ruby193\DevKit 
    2. Generate config.yml file:

       ruby dk.rb init

      and edit it (optional) to add or remove Rubies.

    3. Finally, enhance your Rubies with DevKit:

       ruby dk.rb install
    4. Test installation:

      gem install json --platform=ruby

      you should see “with native extensions”" in the screen messages. To confirm that the json gem is working, run:

      ruby -rubygems -e "require 'json'; puts JSON.load('[42]').inspect"

      This is supposed to return “42” for a successful test. For more see [Jekyll installation guide for Windows] (http://jekyll-windows.juthilo.com/)

(II) Bundler

Now you need to install Bundler into the root directory of your GitHub repository (Important: make sure that you’ve selected gh-pages branch). a. Open the local folder of you repositoyr (~GitHub/RepositoryName) b. Initiate command prompt by typing cmd in the address bar of the File Explorer
c. Type in gem install bundler in the command line
- the text should say that the 1 gem has been installed

(III) Jekyll

  1. Create a text file Gemfile.txt in the root of the repository
  2. The content of the file is

    source 'https://rubygems.org'
    gem 'github-pages'
  3. Rename Gemfile.txt into Gemfile
  4. Run command line bundle install
    The code in step (d.) should executed for each repository you want to publish as a website, whereas the installation of Bundler (step II.) is done once per machine.

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)
}
  1. 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.

  2. 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
  1. Re-run the steps 1-3 from the previous subsection. The comments should be enabled now.
comments powered by Disqus