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")

2. 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 expend some time figuring out what theme is best for you. In my case, here are some themes that I considered:

• Academic: If our 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 our 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 it repository. Look for the Homepage button in the Theme page you like. Here is the one for Casper-two:

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 down or copy that as eueung/hugo-casper-two

Once you have our 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

In the next window you are going to 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

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

2. The fist thing you will see in Rstudio is the config.toml file containing all the parameters to setup our 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 our Google analytics code (googleAnalytics = "") and our 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.

3. 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 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 our are creating a new post or modifying the theme.

If you didn’t ask for it before, blogdown also have installed some posts 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

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 our root folder for our 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 are in 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 our 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 our 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 our posts from WordPress to Hugo. I chose exitwp:

• Download exitwp by cloning or downloading the zip file of the repo.
• Export our WordPress blog using xml. To do this, access the admin of our WordPress blog (MySite -> Settintg -> Export) and export all. Here is a guide to do that.
• 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 our 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 ~/blog/casper-two/public/*")
blogdown::hugo_build(local=F)
system("~/blog/casper-two/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 our 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=our_user_to_our_blog_domain
HOST=our_dream_host_machine.dreamhost.com
DIR=our_blog_domain/
rsync -avz --exclude-from 'exclude-list.txt' --delete public/ ${USER}@${HOST}:~/${DIR}
exit 0

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 our 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 our 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 our blog is crucial, look for a theme that have already search implemented

• Permalinks structure and slugs: you are migrating our blog but you don’t want to lose the backlinks to our blog. Have a look a the permalink structure in our older WordPress blog. In my case a typical post had this structure:

http://estebanmoro.org/2009/08/post-title/

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 post in our 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.