Tutorial part 1: Getting started
by Danielle Navarro, 10 Jun 2020
The aim of caladown is to provide a simple Hugo template suitable for R users who want to build a website or start a blog, and is designed to be compatible with both blogdown and hugodown. In this tutorial, I’ll show you how to get started. The assumed reader for this tutorial is an R user who has some experience with R Markdown, but is unfamiliar with blogdown, hugodown, or Hugo itself.
Blogdown or Hugodown?
The first decision you need to make is which R package to use, blogdown or hugodown? Both allow you to design and manage static websites within R, and both allow you to write pages/posts as R markdown documents. However, there are differences: blogdown blurs the roles played by Hugo and R, which can lead to some degree of messiness. In contrast, hugodown tries to maintain a clean separation: the role of hugodown is to translate your R markdown files into a “plain” markdown format that Hugo knows how to read, and then leaves the rest of the process to Hugo. To me, the cleaner separation in hugodown is highly desirable: but it is currently an experimental package, so some caution is warranted!
To make things as easy as possible, the caladown package contains installer functions for both hugodown and blogdown. If you want to use blogdown, you can create a new site with the following command. Just change
"path_to_blog_folder" to something suitable:
Blogdown will download the calade template and generate the example site (i.e., this one!), and you are ready to get started. The
create_blogdown_calade() command is just a very thin wrapper around
blogdown::new_site(), so if you want to customise the install you can pass arguments to
new_site() via the dots
If you want to use hugodown, the installation command is this:
Note that because hugodown makes different choices to blogdown regarding what is and is not automated, you may need to install the appropriate version of Hugo first. The command for this is:
Once you have installed Hugo and called the
create_hugodown_calade() function, hugodown will download the calade template, configure the site appropriately and then knit all the R markdown files to “Hugo flavoured markdown”. Please note that the success of this knitting may depend on the version of pandoc you have installed, which you can check with
rmarkdown::pandoc_version(). For versions prior to 2.1 the knitting may not be successful, and
create_hugodown_calade() may produce an error. If this happens it may be useful to note that the you can call this function setting
knit = FALSE and it will set up the blog without attempting to knit the R markdown files.
Regardless of whether you choose to use blogdown or hugodown, if you are using RStudio you will end up with a new project opened in a new session. To create a preview of the site use one of the following two commands:
Most of the settings that you’ll initially want to play with are in the
config.toml file. The file is (I hope) fairly well documented, so you can see what most of the settings do and how to configure them. For example, here’s a snippet:
# These settings specify the title for your blog, # and the name of the Hugo theme that it uses. title = "A minimal Hugo website" theme = "calade"
The snippet above is what you should see if you are using hugodown. If you are using blogdown it will be slightly different: the theme folder will have been automatically renamed from
"hugo-calade", and this will be reflected in the
config.toml file. Either way, take a look at the config file, change a couple of things if you like, and then you’re ready to start blogging!
Your first post
Creating posts or pages is (usually) pretty straightfoward in both blogdown and hugodown. In blogdown, you can use the
new_post() function to create a post, and all you need to do is specify the title:
blogdown::new_post(title = "My new post")
In hugodown, the
use_post() function is similar but not quite identical. The main thing you need to do is specify the
path that you’d like the new page to have. So if I want my website to create a page at
https://myfancywebsite.com/post/my-new-post or whatever, the command I would need is this:
hugodown::use_post(path = "post/my-new-post")
Either way, whether you are using blogdown or hugodown, you should now be looking at a new R markdown document that you can start editing!