Jerid Francom bio photo

Jerid Francom

Associate Professor of Spanish and Linguistics
Romance Languages
Wake Forest University

Curriculum vitae

Email Twitter Github Stackoverflow Last.fm

I’ve been exploring ways to make blogging R code easier. In this post I discuss my research in publishing to Wordpress and also Jekyll from Rmarkdown documents. I’ll first say something about some code I wrote/ adapted for converting .Rmd to Wordpress. Subsequently I’ll run over Jekyll sites on Github and how to streamline the process to publish posts with R code embedded.

Publish to Wordpress

When I first starting looking into matters, I was using a Wordpress site hosted on Wordpress.com. I did some research on how to knit and send an .Rmd file to Wordpress with all images going along for the ride. I found Yuhui Xie’s documentation on the official Knitr page which was very helpful and some documentation on uploading images to imgur.com.

This approach requires the knitr, markdown and RWordpress packages. First we set up some options in knitr to adjust the figure sizes and upload them to imgur.com.

library(knitr)
# Set figure dimensions
opts_chunk$set(fig.width=5, fig.height=5)
# Set figures to upload to imgur.com
opts_knit$set(upload.fun = imgur_upload, base.url = NULL) 

Next let’s get to knitin’. The knit() function will create a

rmd.file <- "yourfile.Rmd"
# Knit the .Rmd file
knit(rmd.file)
# Set up input/ output files
markdown.file <- gsub(pattern = "Rmd$", replacement = "md", x = rmd.file)
html.file <- gsub(pattern = "md$", replacement = "_pub.html", x = markdown.file)

Now we’ll load the markdown package and convert the .md file we knitted earlier to an .html. Using the fragment.only parameter we can drop the YAML info that is part of the Rmarkdown file.

library(markdown)
# Removes 'yaml' information
markdownToHTML(file = markdown.file, output = html.file, fragment.only = TRUE) 

All that’s left is to set up your Wordpress site’s credentials and then send the post. Note that the parameter publish = FALSE in the newPost() function means that the post will be added as a draft. This is helpful if you want to preview the post and add tags and categories before publishing.

library(RWordpress)
# Set your WP username, password, and your site URL
options(WordpressLogin = c(your.username = 'your.password'), 
        WordpressURL = 'https://your-wordpress-site.com/xmlrpc.php')
# Create a line-by-line text vector
text = paste(readLines(html.file), collapse = "\n")
# Send to Worpdress
newPost(list(description = text, title = "Your post's title!"), publish = FALSE)

I put together a command-line script that you can find here.

Publish to Jekyll and host on GitHub

Setting up your site

After poking around on the web I was intrigued by the Jekyll publishing framework and hosting on GitHub. After some reading and browsing around other Jekyll sites on GitHub, I decided to fork the minimal-mistakes Jekyll theme by Michael Rose.

You could find any number of themes on the web that have the main configurations already set up. Michael Rose has a few, but you can also find good basic themes using Jekyll-bootstrap. If you go this way you’ll have a similar set of steps to get up and running.

Requirements: a GitHub account, Ruby and RubyGems installed, and a *nix system with git installed.

On Github:

  • Find a Jekyll theme to work with on GitHub and fork it
  • Edit the settings of this forked repository changing the repository name to gitusername.github.io

On your local system:

  • Fire up Terminal
  • Make sure you have git installed/ updated.
  • Clone your new repository
git clone https://github.com/francojc/francojc.github.io.git

Now you will have the remote repository mirrored on your local system. If you’d like to be able to develop locally you’ll need to install Jekyll (and dependencies).

gem install bundler

You can now preview the site locally by running:

jekyll build
jekyll serve

Then you should be able to view your site at http://localhost:4000/.

After you’re feeling pretty great about getting a site up in no time, it’s time to personalize your site. To understand how this works I’ve copied/adapted the scaffolding schema from the minimal-mistakes theme as an example.

minimal-mistakes/
├── _config.yml
├── _data/
|    ├── navigation.yml
├── _includes/
|    ├── _author-bio.html        # bio stuff layout. pulls optional owner data from 
|    ├── _browser-upgrade.html   # prompt to install a modern browser for < IE9
|    ├── _disqus_comments.html   # Disqus comments script
|    ├── _footer.html            # site footer
|    ├── _head.html              # site head
|    ├── _navigation.html        # site top navigation
|    ├── _open-graph.html        # Twitter Cards and Open Graph meta data
|    └── _scripts.html           # site scripts
├── _layouts/
|    ├── home.html               # homepage layout
|    ├── page.html               # page layout
|    ├── post-index.html         # post index layout
|    └── post.html               # single post layout
├── _posts/                      # MarkDown formatted posts
├── _sass/                       # Sass stylesheets
├── _templates/                  # used by Octopress to define YAML variables for new posts/pages
├── about/                       # sample about page
├── assets/
|    ├── css/                    # compiled stylesheets
|    ├── fonts/                  # webfonts
|    ├── js/
|    |   ├── _main.js            # main JavaScript file, plugin settings, etc
|    |   ├── plugins/            # scripts and jQuery plugins to combine with _main.js
|    |   ├── scripts.min.js      # concatenated and minified _main.js + plugin scripts
|    |   └── vendor/             # vendor scripts to leave alone and load as is
|    └── less/
├── images/                      # images for posts and pages
├── 404.md                       # 404 page
├── feed.xml                     # Atom feed template
├── index.md                     # sample homepage. lists 5 latest posts 
├── posts/                       # sample post index page. lists all posts in reverse chronology
└── theme-setup/                 # theme setup page. safe to remove

Key areas to focus on in this scaffolding are the _config.yml and _data/navigation.yml files and the _posts and images directories. The _config.yml file is where you make site-level configuration changes. The _data/navigation.yml is where you set up your navigation. And the _posts and images directories is where your markdown files and images will be added.

Let’s do a quick test. Create a markdown file with the .md extension (manually or via knitr). Then rename that file with the format 2014-12-19-my-filename.md. Before we copy the file into the _posts directory, we need to prepend some meta information (aka “Front matter”) to the file:

---
layout: post
title: "My first post"
---

# My first post

This sure is fun...

Go ahead and move the 2014-12-19-my-filename.md file into _posts/. Then return to the terminal and run:

jekyll serve

Preview, ooh’s and aah’s.

To create pages, edit the navigation, and other changes I will refer you to the minimal-mistakes documentation.

Publishing

Now we want to be able to convert a .Rmd document to a .md document and then prepare the figure paths to look for our figures in the images directory in our Jekyll site. I found a nice base function that uses knitr and knitr options to do just that at jfisher-usgs.

library(knitr)
my.jekyll.site <- "gitusername.github.io"
KnitPost <- function(input, base.url = my.jekyll.site) {
  opts_knit$set(base.url = base.url)
  fig.path <- paste0("images/", sub(".Rmd$", "", basename(input)), "/")
  opts_chunk$set(fig.path = fig.path)
  opts_chunk$set(fig.cap = "center")
  render_jekyll()
  knit(input, envir = parent.frame())
}

And then we can run it

KnitPost("2014-12-19-my-filename.Rmd")

You’re .Rmd will have been converted to a .md file with the appropriate code syntax, and if you have figures in your .Rmd then they will be found in the images/my-filename/ directory. Now drop the my-filename directory (containing the figure images) into the images/ directory and move the my-filename.md file to the _posts directory in the Jekyll site.

You can preview your work with jekyll serve but the images will not render until they are uploaded to our gitusername.github.io site. So let’s do that.

Open Terminal and run:

git add --all
git commit -m "Initial configuration and post"
git push

Now you can visit your GitHub site and marvel at your work.

Again, I put together a command-line script to make it easier to run this script. You can find it here.