/ #blog #R 

Setting up our blog with RStudio and blogdown I: Creating the blog

Last month I migrated my blog from Wordpress to Hugo and blogdown. Now I can post from RStudio using R/markdown, which allow me to create interactive posts including R code. It has been such a good experience that I decide to write down how to do it with three posts to help others.

  • This one about to setup the blog.
  • Part II explains my workflow of creating new posts.
  • and Part III on how to modify the theme.

But before starting, a disclaimer: I am not a programer, designer or web developer. Just a normal user of Rstudio and blogdown. This is not a technical guide, just some notes about how I set up my blog to help other people like me. So maybe there is a simpler, cleaner and more standard way to do it. If so, comments are welcome!

First let’s take a look at the different tools that we are going to use:

  • Hugo: is a open-source framework for creating static websites. No need for a database to store our posts again (Wordpress) or to use website builders (Squarespace). The good thing about a static website is that it is much faster than other solutions. Pages are clean and download fast, which is the main reason I migrated from the bloated-pages Wordpress experience. Hugo will be the engine behind the creation of our blog.

  • Blogdown: is a R package to create websites using R/markdown as our language and Hugo as our engine to render our posts into html. As you will see blogdown takes care of the Hugo part, so no need to install anything else to start your new blog.

  • R Markdown We will write posts using R/markdown. If you are not familiar with this format, have a look into it. Basically a R/markdown file is a plain text file in which you have:

    • A YAML header at the beginning (with author, date, title, parameters, etc.) surrounded by ---.
    • After that you can start typing our text, formating it using simple codes or,
    • Introduce R code chunks whose output will be rendered in the final HTML.

Creating the blog

Creating a new blog cannot be easier. Before starting this is what we need:

  1. RStudio and the blogdown package:
install.packages("blogdown")
  1. Choose a theme. Yes, you have many themes in Hugo. And believe me, this step is crucial, because you are going invest some time to organize our posts, the look of the theme, etc. Creating the new blog could be just 5 minutes, but modifying the theme and adapting our content to it can take weeks. So you might want to spend some time figuring out what theme is best for you. In my case, here are some themes that I considered:

  • Academic: If you are in academia this is probably the best theme for you. It is well documented, contains some extensions and a lot of people are using it, so there is a whole community behind it. But it takes a lot of work to adapt the content to it, specially if you have a lot of papers, talks, posts, etc. or you are coming from another platform like Wordpress. This is why I didn’t chose it.

  • Tranquilpeak: This is a great simple theme. It is easy customizable. This is a good option if you have a list of posts and what to set up a beautiful and simple blog.

  • Casper Two: Casper Two is a personal blogging theme. It is beautiful and simple and it was by choice, since it looked similar to my previous Wordpress theme (which I did like).

Once you have decide the theme is important to locate its repository. Look for the Homepage button in the Theme page you like. Here is the one for Casper-two:

{width=80%}

As you can see in the top left corner of the webpage, the repository for this theme is maintained by eueung in the folder hugo-casper-two. So write it down or copy that as eueung/hugo-casper-two

Once you have chosen the theme, we are ready to go in 3 simple steps:

  1. Open a new project in RStudio: File → New Project → New Directory → Website using Blogdown

{width=60%}

In the next window, specify the directory name of the blog, the subdirectory where the blog is going to be place and the theme. Here is what it looks in my case

{width=60%}

Hit the Create Project and you are done! You have just created your fist blog.

  1. The fist thing you will see in Rstudio is the config.toml file containing all the parameters to setup the blog. At this point:
  • Change you baseurl to be the final one. In my case is baseurl = "http://estebanmoro.org"
  • You can also change the title, subtitle, description etc.
  • Use your Google analytics code (googleAnalytics = "") and your disqus shortname (disqusShortname = "") to add analytics and comments to our blog. Here is a nice post by Peter Baumgartner about how to install disqus on Hugo.
  1. Let’s build the blog! You can do it one-time using
blogdown::hugo_build()

or interactively using

blogdown::serve_site()

In the latter case, a server is running underneath so everytime you edit/change a post, put a new image in /img (see below) or the modify the config.toml, the site is rebuilt by Hugo. Also the blog appears in the viewer pane. This is the best way if you are creating a new post or modifying the theme.

If didn’t set it before, blogdown has also installed some post examples so you can have an idea of how it looks like.

Understanding the blog directory structure

Before starting to post to our new blog, let’s have a look at the directory structure that has been created. In my case, I created the blog in ~/best_blog_ever which looks like this

{width=80%}

The first file best_blog_ever.Rproj is the blog project we have just created. All the new posts go into the content/post folder. You can see there that already we have a number of them. They are in the markdown format (.md) and there is one in the R markdown format (.Rmd).

You also have a folder named static. Think of it as the root folder for the new blog. That means that if there is file there named cv.pdf it can be access as http:/estebanmoro.org/cv.pdf. The folder img is the perfect place to put our images/pictures. For example, if there is a file picture_vacations.png in the img folder, you can include it in our markdown post using

![](/img/picture_vacations.png)

When Hugo builds the blog, the final html files and structure go into the public folder. This is the static version of the blog and the one we will deploy to our domain.

Finally the folder themes contains all the formating for the new theme. I don’t recommend to touch it unless you really know what you are doing. We will see in Part III how to modify the theme.

Migrating our content

I had a lot of posts in my previous Wordpress blog and didn’t want to lose them. Luckily there are some tools to migrate your posts from Wordpress to Hugo. I chose exitwp:

  • Download exitwp by cloning or downloading the zip file of the repo.
  • Export your Wordpress blog using xml. To do this, access the admin of our Wordpress blog (MySite -> Settintg -> Export) and export all. Here is a guide that shows you how to do it.
  • Put our Wordpress xml file in the wordpress-xml folder of our exitwp directory.
  • Edit the config.yaml file to change our setups for the migration. For example, you can change the directory where the migrated posts are going to be created by changing the build_dir parameter.
  • Run it by typing ./exitwp.py in the console from the directory of the unzipped archive.
  • If everything went well you will have a new build directory with all the posts in markdown format. Select the ones you want to keep and move them to the content/post folder of our blog. Depending on our old blog structure you might also have other files in the build directory.

Deploying the blog

CAUTION: we are going to overwrite the blog in our actual domain, so before proceeding, make a backup of it or export it as explained before.

Now we are ready to deploy it to our new domain. Here is the commands in RStudio that I have to do it:

system("rm -r ~/best_blog_ever/public/*")
blogdown::hugo_build(local=F)
system("~/best_blog_ever/deploy.sh")

The fist command simply erases the public directory where the new version of the blog is going to be built. This is probably not needed, but it gives me peace of mind :).

The second command builds the blog. Note the local=F flag which tells Hugo to build a deployment version of the blog, meaning that all the posts with draft: true in the YAML will not be rendered. This will be explained better in Part II

The third command is my personal deployment script. Although most of the guides out there show you how to deploy your new blog using Netlify and/or GitHub, I am using my own domain and space at Dreamhost. Then to update my blog I simply synchronize the public directory with the root directory of my domain. Here is the deploy.sh script

#!/bin/sh 
USER=your_user_to_our_blog_domain
HOST=your_dream_host_machine.dreamhost.com
DIR=our_blog_domain/
rsync -avz --exclude-from 'exclude-list.txt' --delete public/ ${USER}@${HOST}:~/${DIR}
exit 0

Change your your_user_to_our_blog_domain and your_dream_host_machine to your own dreamhost user and machine. The synchronization is down using rysnc. You might also notice that I have excluded some files in the synchronization which are specified in the file exclude-list.txt. In my case I only have the .htacces file there.

And that’s it. If everything went well, you have migrated your blog from Wordpress to blogdown in no time.

Comments

Although I love blogdown and how fast is to built and create new content, there is a couple of things that you might consider before using blogdown for our blog:

  • No search: The content generated is static. That means that you have lost the possibility for the users to search your content. In most Hugo themes there is no “search” button. There is however a possibility to implement searching in our blog using search engines like lunr or angolia. But my experience is that those are difficult to implement. If searching within your blog is crucial, look for a theme that have search already implemented

  • Permalinks structure and slugs: you don’t want to lose the backlinks to your old blog. Have a look a the permalink structure in your older Wordpress blog. In my case a typical post had this structure:

http://estebanmoro.org/2016/02/more-people-more-fun-the-scaling-of-events-in-cities/

so the slug for that particular post was 2016/02/more-people-more-fun-the-scaling-of-events-in-cities/. Most likely, exitwp has put our old slug (the URL valid name for our post) in each of the new markdown post’s YAML, so there is no need to change anything. But check it just in case. Specially for those posts in your blog that have a lot of backlinks.

If you want to keep that format for the permalinks for new posts, modify the [permalinks] parameter in the config.toml accordingly.

Author

Esteban Moro

Professor at Northeastern University. Working on Complex Systems, Social Networks and Urban Science.