First site

The first site I installed used the default options, including the Hugo theme from Yihui’s site, Lithium. This was a good first step because it let me see the folder structure of a Hugo site and how some of the different options and meta files (e.g., config.toml) changed the site.

Current site(s)

However, I didn’t ultimately like the Lithium theme. So, I went looking for some templates at: https://themes.gohugo.io/

After looking around a bit I came across the theme Hugo Future Imperfect Slim (HFIS), which had some nice built-in features, such as social media sharing, and icon links from Font Awesome places like GitLab, ORCiD, Research Gate, etc. This being an academic blog, I thought that was nice.

Initially I tried changing the theme of my first site using blogdown::install_theme(), but I quickly became disoriented, as I didn’t really know what the `config.toml file was telling me.

To help me understand what was going on with the theme, I ended up building two more sites. Turns out when you build a site in blogdown you have the option of populating the site with sample blog posts and the example site from the theme. So what I did was I build a “skeleton” site with HFIS, where I populated nothing, and then I built the example site in another folder. This allowed me to see how the two sites differed and slowly build the site I wanted around my understanding of the example site.

config.toml

Like Jekyll, Hugo appears to use a config file for a lot of site functionality: config.toml. My file has different “sections” and “subsections” enclosed in square brackets:

• (header): The top of the toml file seems to have some global options
• [params]
  • mainSections: Seems to be the order in which pages are displayed on the home and blog/ pages. For that reason I have “post” first, because I want my blog posts to display first.
  • [params.meta]
  • [params.header]
  • [params.intro]
    • [params.intro.pic]
  • [params.sidebar]
  • [params.footer]
• • [[menu.main]]
    • name: The name of the page.
    • identifier: Seems to be the name of the folder the content will go into.
    • url: Relative path of the page. Note the “/page/” syntax.
    • pre: A symbol representing the page, from Font Awesome.
    • weight: I think this is display importance for when the display windo changes.
• [Languages]
  • [Languages.en]
• [social]

blogdown

touch .Rprofile
nano .Rprofile
#Once inside nano
options(blogdown.ext = ".Rmd",
  blogdown.author = "Jason Mercer",
  blogdown.subdir = "blog")

#Note the blank line -- R ignores the last line, so need make sure a trailing
# line is included.
#Exit nano and check that the edits occurred
cat .Rprofile

touch _output.yml
nano _output.yml
#Inside nano
blogdown::html_page:
  out.width: '100%'
  dev: 'svg'

Hugo front matter (yaml/toml/json header information)

Front matter is the stuff that goes at the top of a post or other content. This is similar to Jekyll. Basically, the front matter is metadata about the post or content. For more about front matter: https://www.youtube.com/watch?v=Yh2xKRJGff4

Here is a list of front matter variables that Hugo is aware of: https://gohugo.io/content-management/front-matter/

Note: My site is setup to use yaml front matter variables. This was an option (check box) when I made the site: “Convert all metadata to YAML”. I didn’t know what this meant at the time, but apparently you can supply front matter to Hugo as yaml, toml, or json. I think by converting all metadata to yaml it makes the interface more consistent, but I don’t know that for sure.

Some useful predefined variables (that all Hugo sites know):

• date
• description
• images
• linktitle: I think this can be used as an alternative to the title, if the title is really long.
• slug
• summary
• title
• type: For blog posts on my site I always need to set this to “post” for the blog entry to register properly.
• weight

Some variables that I think are defined by my theme:

• author
• categories
• featured
• featuredpath

blogdown front matter

The yaml used in a typical knitr .Rmd file also applies to blogdown posts. For example, take the yaml header used to create this document. In this case the output variable uses blogdown’s html_page, which can then take arguments, like toc, that I’m used to dealing with from knitr.

---
title: Notes on setting up my new blogdown/Hugo site
author: Jason Mercer
date: '2019-11-08'
slug: notes-on-setting-up-my-new-blogdown-hugo-site
categories:
  - meta
tags: []
description: ''
images:
  - ''
linktitle: ''
output:
  blogdown::html_page:
    toc: true
---

A special note about the featured and featuredpath variables

There isn’t much documentation on these variables, so I had to play around with them for a while before I understood how to use them since there isn’t much documentation on how they work and Hugo’s code is still foreign to me.

1. featured is the name of the image used as a thumbnail.
2. featuredpath is the location of the image. It is assumed that the image from featured is located in /static/img/blog

In some cases the assumption of featuredpath is fine, but when I want to use images from the knitr output, I can’t use this path convention. Further, the featured image must be a raster graphic (e.g., jpeg, png). It was the combination of these two issues that was giving me serious headaches.

Below is my work around for using an image generated from my analysis as the “featured” image of the blog post:

1. Figure out which image I want to use. Name the knitr chunk something that can be used to identify the image a bit easier.

2. Use the dev argument to specify which kinds of images you want to use.

3. It’s important that you specify the extions (e.g., .svg) that you want to show up in the actual blog first (e.g., svg is before png).

4. As an example, this is what the chunk options might look like:

   r chunk_image, dev=c('svg', 'png'), eval=FALSE

5. The two image files will be named with the following pattern: -.. From the example above, assuming their is only one image in the chunk, the two files will be called:

   1. chunk_image-1.svg
   2. chunk_image-1.png

6. These files will be located in: `static/blog/---_files/figure-html

7. Given this pattern, and the assumption the featurepath variable makes, this means that we have to assign featured and feature path the following values to generate the right thumbnail for the post (expanding on our example):

   1. featured: chunk_image-1.png
   2. featurepath: ../blog/2019-11-08-my-blog-post_files/figure-html

8. For the feature path, all one needs to do is remember ../blog/ and _files/figure-html and combine that information with that of the date variable and slug variable.

9. You need to makes sure the images variable is removed. It seems this pathway (default: ’’) overrides the featuredpath.

Here is what the yaml metadata will look like for a minimally working example (R chunk with image is names “iris”):

---
date: '2019-11-09'
slug: hello-hugo-and-blogdown
featured: iris-1.png
featuredpath: ../blog/2019-11-09-hello-hugo-and-blogdown_files/figure-html/
type: post
---

When there are not featured images

I discovered that if I leave the images variable as blank in the front matter it creates a “blank” image in Firefox. So, it seems like best practice to just delete all the variables that aren’t filled out, in order to avoid this kind of behavior. Below is an example of my updated header for this post.

---
title: Notes on setting up my new blogdown/Hugo site
author: Jason Mercer
date: '2019-11-08'
slug: notes-on-setting-up-my-new-blogdown-hugo-site
categories:
  - meta
tags:
  - hugo
  - tutorial
type: post
output:
  blogdown::html_page:
    toc: true
---

About

For this page, I more or less just copied over the about page from my Jekyll blog. At first I had some problems with the images not displaying properly, but I found out that my custom html/css just needed some “div” tags around them.

<!-- This works -->
<div>
  <figure-right>
    <img src="/img/about/about-viking.jpg">
    <figcaption>
      Packrafting the Anaktuvuk River, North Slope, Alaska.
    </figcaption>
  </figure-right>
</div>

<!-- This doesn't work; my captions wondered off -->
<figure-right>
  <img src="/img/about/about-viking.jpg">
  <figcaption>
    Packrafting the Anaktuvuk River, North Slope, Alaska.
  </figcaption>
</figure-right>

Research

Using the lesson from the about page, translating this page from Jekyll to Hugo was smooth.

CV

For this page I’m trying to replicate some functionality developed by Noam Ross, who developed an R script for downloading and populating his CV from ORCiD. Pretty neat! His script is located here.

The first issue I ran into was automatically downloading my ORCiD information. It appears I need use OAuth with the ORCID API. To get that information I performed the folllowing steps:

1. Ran rorcid::orcid_auth()

2. Logged into ORCiD and authorized the use of OAuth

   library(rorcid)
   orcid_credentials <- orcid_auth()

3. I then copied the key into my .Rprofile file

   options(blogdown.ext = ".Rmd",
     blogdown.author = "Jason Mercer",
     blogdown.subdir = "blog",
     orcid_token = "XXXXXXX...")

4. Then I added .Rprofile to my .gitignore file so my information wouldn’t be exposed.

To test if this solution worked I restarted R (ctrl + shift + f10) and re-ran the rorcid code for downloading data and it worked!

However, not all of the DOIs associated with my works seem to be registering with CrossRef (though the actual DOIs do properly link to the underlying material), so I’ll have to figure that out at some point.

It looks Noam also included some manual publication information. I may end up using that to fix my problem, but for the time being I’m ignoring the manual publication stuff.

The result of the script are 4 yaml files in the data/ directory:

• education.yaml
• employment.yaml
• papers.yaml
• papers_orcid.yaml

I had a bit of trouble with the education yaml, so I ended up modifying Noam’s code a bit. For example, I ended up hardcoding “(Excpected) 2020” for my graduation date, as Hugo didn’t know what to do with the empy file. I also added an “order” element to the education lists, to help with getting my education in the right order. These changes are refelected in both the script and the file layouts/cv/cv.html (which I’ll talk about later).

The next big issue was figuring out how to put all that yaml information together as there wasn’t an obvious way to use it in the context of markdown. This took a bit and I had to learn about “sections” in Hugo.

Basically, I:

1. Added a cv/ directory to content/.
2. In cv/ I added an _index.md file (a convention in Hugo) with a single line of YAML: the title (“Curriculum Vitae”). This file basically “initializes” the layout I want, which aggregates all the yaml I made earlier.
3. I then made the file layouts/cv/cv.html. This file is basically just themes\hugo-future-imperfect-slim/layouts/_default/single.html, except that I replace the “{{ .Content }}” code with some code from Noam.
4. The code I used come’s from Noam’s layouts/section/vitae.html. He had a lot of extra stuff in there, so I just used some of the information from the eduction, professional experience, and publications sections. It wasn’t crazy hard to figure out, but is definitely weird looking.
5. Last, to get the professional experience code to work, I had to borrow a partial from Noam’s site: layouts/partials/work.html. This file I did not edit, but put straight into my own layout folder.
6. Other than that I just made some aesthetic edits that matched my own theme a bit more, compared to Noam’s site.

Tags

To generate the tags page I took advantage of some default behavior used by Hugo related to “taxonomies”. The Mike Dane video on taxonomies was helpful in understanding how to deal with this.

Basically, the theme I’m using comes with a “categories” page, but not a “tags” page – despite tags being common front matter. However, I wanted a way to be able to see and access tags the same way as the categories. The way I did this was by more or less copying the categories info in the menu table (menu.main) of the config.toml file. Then I just changed “categories” to “tags”.

This is possible because Hugo automatically makes tags list sites, it’s just that it wasn’t accessed by default from the theme I’m using.

Also, as an FYI, I can make customizable taxonomies (e.g., something besides “categories” and “tags”), if I want to. Maybe later.

List pages

List pages are basically aggregator pages. For example, my home page is a list page, because it’s listing all the blog posts on the page (or some of them). The categories and tags pages are also list pages.

Single pages

Single pages are one off pages. So, for example, my about and research pages are sinlge pages. Also, all the individual blog posts are single pages.

TOML

The primary building block of toml is the key/value pair. For example:

key = "value"

Boolean’s in toml are represented as “true” and “false”

This is super detailed, but the time standard used by toml can be found here.

Arrays can be passed to toml using brackets (and brackets in brackets for multi-dimensional arrays). It seems that arrays don’t need to be the same type. Example:

colors = ["red", "white", "blue"]
nested_colors = [["red", "fuscha", "pink"], ["blue", "cyan"]]

[table]
key1 = "value1"
key2 = "value2"

[table]
key = "value"
[something.else]
key = "another value"
[something.other]
key = "yet another"
  [something.other.thing] # This is really part of an array of tables
  color = "red"
  shape = "round"

name = { first = "Tom", last = "Preston-Werner" }
point = { x = 1, y = 2 }
animal = { type.name = "pug" }

[name]
first = "Tom"
last = "Preston-Werner"

[point]
x = 1
y = 2

[animal]
type.name = "pug"

[[menu.main]]
    name              = "Home"
    identifier        = "home"
    url               = "/"
    pre               = "<i class='fa fa-home'></i>"
    weight            = 1

config.toml

toml: Tom’s Obvious, Minimal Language

All the elements wrapped with “[]” and “[[]]” are related to specific structural elements listed above. It seems that some of these tables are associated with standard behavior in Hugo. For example:

• baseURL
• menu
• paginate

For a full list of the standard key and table values, check out (note that values in parentheses are the defaults): https://gohugo.io/getting-started/configuration/

Based on my understanding of this stuff, and a recommendation in the blogdown book, I added the following code to my config.toml file:

ignoreFiles = ["\\.Rmd$", "\\.Rmarkdown$", "_files$", "_cache$"]

[permalinks]
    post = "/:year/:month/:day/:slug/"

Site setup

My expected site structure: * content/ * about.md * blog/ * … * curriculum-vitae/ * research.md * data/ * .yaml (related to the curriculum-vitae section) r/ * layouts/ * curriculum-vitae/ * partials/ * public/ * scripts/ * get-orcid-data.R * static/ * blog/ * … * img/ * about/ * blog/ * main/ * research/ * themes/

Blog titles

For some reason the behavior of blog titles was set to break words, rather than wrap them to the next line, like normal. I was able to find the css associated with this choice deep in main.scss. That is, it was in .post -> header -> word-break, which I changed from break-all to normal.

Also, it turns out I need to re-render the site everytime I make a change to the css otherwise the changes will not be updated in the public file, which is what I’m really viewing when the site is being served to my local host.

Hugo code

As far as I can tell, there are a couple of ways of getting relative links to work in blogdown/Hugo. The most verbose, but closest tied to Hugo itself (which should mean it always works) is to call the html itself via htmltools::HTML. For example, to link this post I would use:

[this post](`r htmltools::HTML('{{< ref "/blog/2019-11-08-notes-on-setting-up-my-new-blogdown-hugo-site" >}}')`)

This results in: this post. Also not that the set of quotes needs to be in the order provided in the chunk above. That is, ’ needs to wrap the Hugo reference and " needs to wrap the blog reference.

Blogdown code

But that looks complicated. Can I simplify the code? Maybe. Here is some code that is little less verbose:

[this post](/blog/notes-on-setting-up-my-new-blogdown-hugo-site)

And this is how it will render: this post.

Note: This code works, at least, on the GitLab site, so I shouldn’t need to use the super verbose form of the code.