Getting Started with Knitr-Lanyon
13 Dec 2015Introduction
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-lanyon
repository to set up, with minimal fuss, a Jekyll-powered site with good styling borrowed from Mark Otto’s Lanyon 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 Lanyon-themed blog, check out the same R-set-up but using Mark Otto’s Hyde theme with a fixed 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.
Preliminaries
Platform
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-lanyon 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.yml
file. Make some choices:
- Change the
title
anddescription
. - Change the value of
baseurl
as per the commented directions. For a site associated with a repository namedmyProject
, 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 asbaseurl
, with the addition of ‘/’ at the end. So for a project site it’s “/myProject/” and for a user site it’s just “/”. - Change
url
. Since you are pushing to Git Hub, it can behttps://yourgithubusername.github.io
. - Decide if you would like people to be able to comment on your posts. If you want this, leave
disqus
attrue
and 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. Setshortname
accordingly. If you don’t want commenting, simply setdisqus
tofalse
. - Change
twitter
andfacebook
tofalse
if 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
Updating the 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:
Authoring
From the _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:
year-mm-dd-your-brief-post-title.Rmd
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:
https://yourgithubusername.github.io/yourProjectName
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 _posts directory.
Further Customization
Make the site entirely your own by erasing my posts. Delete the unwanted R Markdown sources, and delete their processed Markdown derivatives from the _posts
folder.
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 Lanyon 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 public/css/custom.css
file.
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!