Site icon R-bloggers

Creating your Jekyll-Bootstrap powered blog for R blogging

Fellgernon Bit - rstats

[This article was first published on Fellgernon Bit - rstats, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

As you might have noticed, I recently decided to move Fellgernon Bit from Tumblr to GitHub. There are a couple of reasons why I made this change.

  1. I wanted a more professional-looking blog.
    • There are not many R blogs on Tumblr, and well, long text posts are not really meant for Tumblr.
  2. Better code highlighting.
    • I had enabled R code highlighting using the highlighting instructions from Jeffrey Horner (Horner, Part I). The instructions are great! I guess I just got lazy to tweak the CSS of my Tumblr blog to fix some things I didn’t like.
    • I also want to be able to highlight code from other languages, like bash.
  3. Make it easier to embed any HTML code.
    • Yes, you can write posts at Tumblr in pure HTML but sometimes things break as Tumblr doesn’t like them.
  4. Easier process of writing posts using Rmd files.
    • The steps in Horner’s guide (Horner, Part II) are quite involved. Instead of those steps, I was just knitting my posts and then manually copying the html code in the body tags, then pasting it in Tumblr.
  5. Easy way to host figures and link to them.
    • I have previously hosted pictures through Picasa Web Albums, but with the push towards Google Plus they made it harder to embed solo pictures (you can embed Google+ posts though).

I had also previously heard about Jekyll-powered blogs, specially thanks to Yihui Xie’s blog (Xie, English version). At the time when I first learned about this type of blog it seemed challenging so I never dedicated the time to really learn about it. What ended up movitivating me to do so was our new student bloggers group @jhubiostat.

Let me describe how I set up Fellgernon Bit @ GitHub.

Setting up Fellgernon Bit @ GitHub

Creating the Jekyll-Bootstrap blog

My main guide to setup the blog comes from a post by J. Fisher (Fisher, 2012) which points to another of his posts (Fisher, 2012b).

Install Jekyll

Before doing anything, I first had to install Jekyll. To do so I recommend checking the installation documentation (Jekyll Installation).

To install Jekyll, I needed to have Ruby and RubyGems. Since I use MacPorts these are the steps I used:

## Update MacPorts, can take a while!!
sudo port selfupdate
sudo port upgrade outdated

## Search for Ruby and install it
## I think that Jekyll needs 1.9+ since I had 1.8 already installed
port search ruby
sudo port install ruby19
## Set as default version
sudo port select --set ruby ruby19

## Check which version you have
ruby --version

## I manually set mine to be ruby1.9
cd /opt/local/bin
sudo ln -s ruby1.9 ruby
ruby --version 
## This is mine:
## ruby 1.9.3p448 (2013-06-27 revision 41675) [x86_64-darwin12]

With Ruby in place, I could then install jekyll.

sudo gem install jekyll

Note that you can also do this after initializing the blog.

Initialize blog

Following the instructions (Fisher, 2012b) I then acquired all the setup files for Jekyll-Bootstrap. The installation instructions are quite straight forward as you will see (JB Quick Start).

First, I created the lcolladotor.github.com repository on GitHub. As my GitHub username is lcolladotor, by default GitHub will consider the lcolladotor.github.com repository as a GitHub pages repository and publish it. Thus creating lcolladotor.github.io/.

Once the repository was created, I added the Jekyll-Bootstrap files.

## Initialize repo with Jekyll-Bootstrap files
git clone https://github.com/plusjade/jekyll-bootstrap.git lcolladotor.github.com
cd lcolladotor.github.com/
git remote set-url origin git@github.com:lcolladotor/lcolladotor.github.com.git
git push -u origin master

Change theme to Twitter-2.0

Jekyll-Bootstrap includes several themes (JB Themes) which you check on their theme explorer. I think that J. Fisher’s blog looks good with Twitter-2.0 and decided to follow his lead. Furthermore, he has customized a few things (check his blog’s history) which I just plan on using.

## Install Twitter-2.0 theme
rake theme:install git="https://github.com/gdagley/theme-twitter-2.0"

Code highlighting

The default Jekyll highlighting setup uses pygments. I am basing my statement on the documentation for the highlight argument in ?knitr::render_jekyll:

which code highlighting engine to use: for pygments, the Liquid syntax is used (default approach Jekyll)

So I installed Pygments.

## Install Pygments, assuming you have Python installed
curl -O http://python-distribute.org/distribute_setup.py
sudo python distribute_setup.py
sudo easy_install Pygments

Note that (Fisher, 2012b) details some other steps. I basically copied his syntax.css file and saved it as /assets/themes/twitter-2.0/css/syntax.css

Note that you do have to add to _includes/themes/twitter-2.0/default.html the following line:

<link href="/assets/themes/twitter-2.0/css/syntax.css" rel="stylesheet" type="text/css">

As you can see on my own file in line 23 (currently) I am using a Liquid syntax instead of specifying the full path.

Import posts

Next I had to import my posts from Tumblr. Jekyll has a varied set of tools that allow you to quickly import posts which I recommend using if you are migrating your blog (Blog Migrations).

The Tumblr importer allows you to either import them into HTML format or Markdown format. I first tried Markdown, but ran into some problems. So I decided to import them into HTML format, and rename them to Markdown.

## Install importing tools
sudo gem install jekyll-import --pre

## Import the posts
cd ~/
mkdir tmp
/opt/local/bin/ruby1.9 -rubygems -e 'require "jekyll/jekyll-import/tumblr"; JekyllImport::Tumblr.process("http://fellgernon.tumblr.com", "html", true, false, false)'
## There is a post that the converter didn't like, so I had to set to "private" mode


## Rename from HTML to Markdown
cd _posts/tumblr/
for i in *html; do echo $i; filename=$(basename "$i"); filename2="${filename%.*}"; echo $filename2; mv $i ${filename2}.md; done

## Move the posts to _posts
mv ~/tmp/_posts/tumblr/*md ~/WhereYouHaveYourLocalGitRepoCopy/lcollado.github.com/_posts/

I then had to do some manual edits on the posts, specially for code chunks. For example, this post has R chunks which I had to surround by:

To complete the posts, I made sure the YAML front matter was correct and defined categories since I only had tags in Tumblr.

Viewing your blog locally

Once you have the posts, you can use Jekyll to view your blog locally.

## Go to your directory
~/WhereYouHaveYourLocalGitRepoCopy/lcollado.github.com/

## Generate the static view of your blog
jekyll serve

In my case, jekyll serve prompted a couple of errors which I had to go to the posts and edit. For example, some HTML tag that I opened but didn’t close. Stuff like that.

Once you run the previous command, you can then view your site on your browser at http://localhost:4000/

Customizing

The very first thing you must change is the _config.yml file. The file you copied from Jekyll-Bootstrap includes instructions on how to do so. If you learn by example, take a peek at mine.

In my case, I use Disqus for comments and Google Analytics for tracking visits. Since I was also using Disqus for my Tumblr blog, I used Disqus‘ tools to migrate the comments. Finally, I use FeedBurner for my RSS feed, which I was able to update to the new RSS generated by Fellgernon Bit @ GitHub. Thus, the subscribers to feeds.feedburner.com/FellgernonBit didn’t have to change anything.

I also added AddThis Smart Layers with bit.ly shortening to the site and a ClustrMap as you can see in _layouts/page.html.

As for math, I am currently using the rdiscount flavor of Markdown and loading the MathJax script as you can see in _layouts/default.html. However, note that we shoudn’t ask too much power out of Markdown for math (Xie, 2013).

To use rdiscount locally, I also had to install it. I have also tried out kramdown.

## Markdown flavors
sudo gem install rdiscount
sudo gem install kramdown

## I don't remember why I also installed this:
sudo gem install nokogiri

I then customized the index and added other pages:

Since I am interested in getting my blog to be a part of R-bloggers, I created an RSS specific for the posts under the rstats category to comply with their requirements (Add your blog!).

For the category-specific RSS I used feed.category.xml (Jekyll RSS Feed Templates) and created rss-rstats.xml [see atom-rstats.xml if you prefer Atom RSS] which is then processed and converted to feeds.feedburner.com/FellgernonBit-rstats.

Note that I use FeedBurner to then create Twitter updates linking to back to the posts. Also, for the rstats one I add the #rstats hashtag to the post.

Writing an R post

  1. Fisher again explains in detail how to blog using Knitr and Jekyll (Fisher, 2012). Since I use TextMate2 as my text editor, I went ahead and modified his code and created a command to do so.

Basically, I modified the knit command from the SWeave TextMate bundle and added J. Fisher’s code. I saved it under the Menu Actions of the SWeave bundle and linked it to alt + e.

For this to work, I use Google Chrome with the Markdown Preview extension installed.

This is the code for the TextMate command. You could certainly make it much more concise and drop things, but I like to see a quick preview of the post. However, I still recommend using jekyll serve for a final thorough preview of the post before pushing it to GitHub.

Things I might add

Carl Boettiger has a great site –specially the Lab Notebook part– and he describes all the tools he used for making it (Boettiger, 2013). One of the features I would like to add to my site is the history button on the right sidebar he has on his posts which link to the GitHub history of the post. For example check this post and its history. I think that it can be very useful for those interested in any edits made to the posts. For example, I had to fix a couple of things on one of my recent posts as you can see here.

Looking around, I found the code needed for this to work in Carl’s repository: _includes/sidebar.html, _plugins/jekyll-labnotebook-plugins.

However, GitHub currently does not support Jekyll plugins. Meaning that if you use any plugins, you have to create the site locally and then push it to GitHub instead of just pushing the new posts and letting GitHub handle creating the site. It’s not a huge deal, but for now I’ll rely on GitHub and keep things simple for me.

If I were to do it again

Once you install Jekyll, I think the easiest way to set up your own blog is to fork another person’s blog

Then delete their posts, give attribution, and customize things like the blog title and other things you would have to customize on any blogging platform (RSS, comments provider, etc).

Obviously Jekyll gives you much more control over your site, but at the same time, you must also dedicate enough time to learn what to change and make sure that things don’t break.

Post template

To finish describing my setup, here is my post template.

Wrap up

I hope that you will find some of this information useful if you are thinking of starting your R blog powered by Jekyll-Bootstrap and hosted by GitHub.

Note that since the blog is hosted in GitHub, others can send you pull requests to fix things and/or create guest posts. Just as easily you can make it a multi-author blog by changing the collaborators setting of the GitHub repository.

This wouldn’t have been possible without J. Fisher’s posts and many other resources available online.

References

Citations made with knitcitations (Boettiger, 2013b).

Reproducibility

sessionInfo()

## R version 3.0.2 (2013-09-25)
## Platform: x86_64-apple-darwin10.8.0 (64-bit)
## 
## locale:
## [1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] knitcitations_0.4-7 bibtex_0.3-6        knitr_1.5          
## 
## loaded via a namespace (and not attached):
##  [1] codetools_0.2-8 digest_0.6.4    evaluate_0.5.1  formatR_0.10   
##  [5] httr_0.2        RCurl_1.95-4.1  stringr_0.6.2   tools_3.0.2    
##  [9] XML_3.95-0.2    xtable_1.7-1

To leave a comment for the author, please follow the link and comment on their blog: Fellgernon Bit - rstats.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.