Getting Started with Knitr-Hyde13 Dec 2015
The aim of this project is to help students and colleagues who for some reason want to blog on R-related topics. If you have a particular Git Hub project that deals with R and you want to blog about your work as it develops, or if you simply want to blog about R in general, then you can use the material from my
knitr-hyde repository to set up, with minimal fuss, a Jekyll-powered site with good styling borrowed from Mark Otto’s Hyde project. With help from Yihui Xie’s
servr package and knitr-jekyll code you ‘ll be able to write your posts in R Markdown, build and preview the site locally, and push to your Git Hub Pages site when you are ready.
I have tried to minimize what you need to know about Jekyll (and web development generally) in order to get going. You can learn more about Jekyll when it suits you and eventually make thorough-going alterations to my blog-template, but for now I want you to be able to concentrate on getting your content out there to a waiting public.
Note 1: Before you commit yourself to a Hyde-themed blog, check out the same R-set-up but using Mark Otto’s Lanyon theme with the cool toggle-able sidebar!
Note 2 (added Feburary 7, 2017): About nine months after this project was published, the team at RStudio began work on blogdown, a package specifically for R-blogging. You should not use Knitr-Hyde or Knitr-Lanyon unless you have a particular need for those themes.
Jekyll is not officially supported on Windows, so you had best try this with Mac OSX, or with a Linux distribution. (Either way works well, in my experience.) But if you are determined to give it a try on Windows, consult the documentation here.
Get My Files
Consult the Github Pages guide. Decide whether you want a general user site or a site associated with a partcular project repository.
Getting Files for a Project Site
If you don’t already have an existing project but want a project-associated site, then fork my knitr-hyde repository from Git Hub, rename it as you wish and then clone it on your own machine.
If you are using R Studio, then you could accomplish this by creating a new project under version control. The final step of this process clones from your remote site on Github, and you find yourself in the new project on the master branch. Click on the Git tab and then the More menu, and open a shell. You will be in the root directory of your project. Run these commands:
and then exit the shell. You will now be in the local
gh-pages branch of your project. All of your blogging work will be done in this branch. When you want to do actual project work, switch to the master branch.
If you already have a project repository on Git Hub and want a site associated with it, then simply create a
gh-pages branch, delete all of the files, download a zip file of my
gh-pages branch and extract it into your repo while you have your
gh-pages branch checked out.
Getting Files for a User Site
Having created your user respository (
yourgithubusername.github.io as per the GitHub Pages guide), clone your user repo onto your own machine. Stay on your
master branch: you don’t create a
gh-pages branch for a user site. Download a zip file of my
gh-pages branch and extract it into your repo.
Configuring my Files for Your Use
In the root directory, locate the
_config.yaml file. Make some choices:
- Change the
- Change the value of
baseurlas per the commented directions. For a site associated with a repository named
myProject, the base url will be set to “/myProject”. For a user site, it’s just “”, an empty string.
- Change the value of
baseurlknitr. It should always be the same as
baseurl, with the addition of ‘/’ at the end. So for a project site it’s “/myProject/” and for a user site it’s just “/”.
url. Since you are pushing to Git Hub, it can be
- Decide if you would like people to be able to comment on your posts. If you want this, leave
trueand register at the Disqus.com. You will have the opportunity to add Disqus to your site. Do this. As part of this process you will be asked to create a shortname for your site. Set
shortnameaccordingly. If you don’t want commenting, simply set
falseif you don’t want the Tweet and Facebook buttons for your posts.
Get the Packages
Ruby and Gems
You will need to install Ruby, and then install the Jekyll gem and all of the other gems that depend upon it. It’s best if you install the versions of these gems that Git Hub will use to build your page. The currently-used versions are listed here.
That seems like a lot to track of, but fortunately the
github-pages gem keeps all your Jekyll-related gems in sync with Git Hub:
sudo gem install github-pages
In order to stay current with Git Hub, update this gem frequently:
sudo gem update github-pages
github-pages gem updates Jekyll and all of the Jekyll-related gems, too.
The servr Package
You’ll need Yihui Xie’s
servr package. In R, run:
_source folder, find an R Markdown document and open it. You’ll see YAML front-matter at the beginning, like this:
Set the title, author and date as you wish. If your post has categories, list them, for example:
categories: [R, 'Marsupial Studies']
Note that mutli-word category-names are quoted.
Save the post using the date-and-title format:
Write your post. As you go, you can run the R command:
If you are using R Studio then the site will show up in the Viewer. Every time you save a change to your draft post, the site will re-build, so you can preview your change in real time. That’s the genius of Yihui Xie.
The post will be rendered using the Ruby gem
kramdown. Look in my
sample-post for examples of inline and displayed mathematics. Otherwise you can write pretty much as you normally do in R Markdown.
When you are happy with your post, commit your changes and push your
gh-pages branch to Git Hub. You can view your site online at:
Note on Compatibility: If for one reason or another you had already installed Jekyll prior to working with this post, then it’s probably a version different from the one currently used by GitHub. If you want to keep that other version around then you will need to tell
servr::jekyll() to build your site with the Github-compatible version. Suppose, for example that the correct version is Jekyll-3.2.1. Then to preview you would run:
Note on Sample Posts: The package comes with two posts: this getting-started guide and a sampl post that demonstrates several capabilities of R Markdown. In order to ensure that these posts to display correctly for you, go to the
_posts directory and remove the
.md files corresponding to them. When you run
servr::jekyll() command new
.md files will be gnerated in the
Make the site entirely your own by erasing my posts. Delete the unwanted R Markdown sources, and delete their processed Markdown derivatives from the
Styling is provided from Mark Otto’s excellent Hyde project. Hyde comes with eight themes, and you can put the sidebar on the right if you like. Consult the Hyde project README to learn how to make these changes.
If you know a bit of CSS then you might want to play around with the
Eventually you should learn more about Jekyll and the Liquid templating system that Jekyll supports. Then you can customize the site even further:
- adding or taking away sidebar widgets
- displaying author names
- using draft posts
and more. Happy blogging!