This post is meant as an aide memoire for myself of the steps I went through to set up this blog. But maybe it can be helpful for others as well.

Server

My blog is hosted on a 1blu vServer with a Plesk-free Ubuntu 16.04 installation with an Apache webserver. I can conveniently login to the server via ssh. Enabling HTTPS via a Let’s Encrypt certificate was a cinch with certbot.

blogdown

blogdown is an R package (still in beta at the moment) for creating websites written in R Markdown. It uses the static site generator Hugo enhancing it with knitr magic. There is an online book documenting the process of how to set everything up at https://bookdown.org/yihui/blogdown/. As of this writing the book is still in the making but it should be more than sufficient to get you started1.

Installation

First, I created a new project in RStudio and installed blogdown & Hugo:

devtools::install_github("rstudio/blogdown")
blogdown::install_hugo()

The default theme that comes with blogdown isn’t bad but I had a look around at Hugo Themes anyways and decided to go with Beautiful Hugo.

So I called

blogdown::new_site(theme = "halogenica/beautifulhugo")

and the site was live with some example content (including a site configuration file, see config.toml below), at least locally.

I also put the whole project under version control, so you can in fact look at the GitHub repository of this blog at https://github.com/mattflor/www.mattflor.de.

Configuration and Tweaks

Here, I’ll list things I tweaked to my liking so I do not forget.

config.toml

Most variables you can configure in the config.toml file for your website are pretty straightforward and self-explanatory: base URL of your website, your name, social media handles, &c. Just fill in your details and comment out (or delete) stuff you don’t need. For a list of Hugo’s configuration variables, see https://gohugo.io/overview/configuration./

From blogdown’s default theme I adopted the following:

  • Tell Hugo to ignore files generated by the blogdown environment:

    ignoreFiles = ["\\.Rmd$", "_files$", "_cache$"]
  • Add nice permalinks for blog posts:

    [permalinks]
        post = "/:year/:month/:day/:slug/"
  • Use highlight.js for code highlighting (instead of pygments):

    [Params]
        # options for highlight.js (version, additional languages, and theme)
        highlightjsVersion = "9.11.0"
        highlightjsCDN = "//cdn.bootcss.com"
        highlightjsLang = ["r", "yaml"]
        highlightjsTheme = "github"

The [[menu.main]] parts control the navigation bar of the website. I commented out the “Samples” entries, added a “Categories” one, and edited the weights variables of the entries to change their order in the navigation bar.

custom.css

I wanted a slightly different font color scheme so I copied the file ./themes/beautifulhugo/static/css/main.css to ./static/css/custom.css, removed everything not pertaining to colors, and changed the HTML color codes to my prefered ones. For Hugo to pick this additional stylesheet up, I followed https://discuss.gohugo.io/t/how-to-override-css-classes-with-hugo/3033/4: In config.toml, add

[Params]
    custom_css = ["css/custom.css"]

and in ./layouts/partials/head_custom.html, add

{{ range .Site.Params.custom_css }}
    <link rel="stylesheet" href="{{ $.Site.BaseURL }}{{ . }}">
{{ end }}

list.html

I didn’t like that the “About” page was included on the landing page. Following https://discuss.gohugo.io/t/exclude-post-type/5194/2, I copied ./themes/beautifulhugo/layouts/_default/list.html to ./layouts/_default/list.html and changed the line {{ range .Paginator.Pages }} to {{ range where .Paginator.Pages "Type" "eq" "post"}}2.

Also, posts in the listing on the landing page looked messy if their first lines contained code. This can be improved by further editing the list.html file, cf. https://github.com/rstudio/blogdown/issues/21#issuecomment-285747870:

<div class="post-entry">
    {{ if .Description }}
        {{ .Description | safeHTML }}
        <a href="{{ .Permalink }}" class="post-read-more">[{{ i18n "readMore" }}]</a>
    {{ else }}
        {{ if .Truncated }}
            {{ .Summary }}
            <a href="{{ .Permalink }}" class="post-read-more">[{{ i18n "readMore" }}]</a>
        {{ else }}
            {{ .Content }}
        {{ end }}
    {{ end }}
</div>

Now, I can add a description: 'Short description to be displayed on the landing page list.' to a YAML header of a post if I don’t want hugo’s automatic summary.

logo and favicon

I wanted my own logo and favicon, added them to ./static/img and referenced them in config.toml. However, I only managed to have them picked up properly when I deleted all images from ./themes/beautifulhugo/static/img. I guess this had something to do with using the theme’s example site and not understanding where in the layout the example images were referred to…

.Rprofile

I created an .Rprofile file with the following content in the project’s root directory:

options(
    blogdown.author = "Matt Flor",
    blogdown.rmd = TRUE,
    blogdown.method = "html"
)

That way, new posts will be R Markdown by default and contain my name in the author field. I initially wanted to use the “html_encoded” method (https://bookdown.org/yihui/blogdown/methods.html#methods) but something was messing up figure paths so I reverted to the default “html” method…

Deployment

To deploy the Hugo-generated website to my server I use a Linux shell script, deploy, similar to the one shown at https://gohugo.io/tutorials/deployment-with-rsync/:

#!/bin/sh

USER=root
HOST=www.mattflor.de
DIR=var/www/html/

rsync -avz --delete public/ ${USER}@${HOST}:/${DIR}

exit 0

The script will transfer all files in the project’s ./public directory to /var/www/html on my server which is Apache’s default document root. Don’t forget to give execution privileges (chmod +x deploy).

Workflow

  1. Create a “New Post” (RStudio Addin), enter details in the dialog, add draft: true to the YAML frontmatter.
  2. Start local webserver via “Serve Site” (RStudio Addin).
  3. Write post (each time you save the Rmd file, Hugo will automatically update the local site), use git during the writing process as desired.
  4. When satisfied: Remove draft: true and stop the local webserver.
  5. Call blogdown::build_site() (RStudio console).
  6. Run ./deploy (Linux command line).

  1. In addition, https://proquestionasker.github.io/blog/Making_Site/ is a great resource.

  2. With Hugo themes, this is the way to customize.