Tips for using the Hugo academic theme

I recently migrated my personal website and Wordpress blog to blogdown. As an academic, it was natural to use the Academic theme. The blogdown package made the conversion fairly straighforward, but I still had to spend some time figuring out how to work with this Hugo theme.

The source and rendered files for my website are available on GitHub:

Table of Contents

  1. Resources
  2. Start with config.toml
  3. Full content RSS feeds for categories
  4. Modifying the Contact section
  5. Adding a CV
  6. Version control

Resources

This post contains a minimal set of notes that I used to configure specfic parts of the Academic theme and is not a full tutorial on starting a blogdown website. The references and tutorials below are helpful for the initial setup of your site.

Start with config.toml

The key-value pairs in config.toml are pretty straightforward, and I was able to very quickly fill in basic information to populate the home page. The places I’ll mention next are ones where I had to spend a little more time.

Color theme

[params]
  # Color theme.
  #   Choose from `default`, `ocean`, `forest`, `coffee`, `dark`, or `1950s`.
  color_theme = "custom"

This sets the color scheme for your site. I changed the theme to “custom” and made created a file called custom.toml in themes/hugo-academic/data/themes/. I have the following in my custom.toml file:

# Theme metadata
name = "custom"

# Is theme light or dark?
light = true

# Primary
primary = "#328cc1"
primary_light = "#328cc1"
primary_dark = "#DA2536"

# Menu
menu_primary = "#494949"
menu_text = "#fff"
menu_text_active = "#328cc1"
menu_title = "#fff"

# Backgrounds
background = "#fff"
home_section_odd = "#fff"
home_section_even = "#f7f7f7"

The “Primary” section changes the color of links and icons depending on whether you want a dark or light-colored theme. The “Menu” section changes the colors in the top menu bar. The “Backgrounds” section changes the color of the section panels on the first page.

highlight.js

In this section, you can configure the languages for which you want to support syntax highlighting. As mentioned in the comments in this section of config.toml, you can visit https://cdnjs.com/libraries/highlight.js/ to see the list of languages supported (URls ending in languages/LANGUAGE_NAME.min.js). You’ll also see a list of color schemes (URLs ending in styles/STYLE_NAME.min.css). I wanted to know what these color schemes looked like, so I searched and found https://highlightjs.org/static/demo/.

Full content RSS feeds for categories

When I first started building my site with the Academic theme, I noticed that most of my RSS feeds (e.g. https://lmyint.github.io/post/index.xml, https://lmyint.github.io/categories/r/index.xml) contained only a brief summary of my posts in the description tags as opposed to the full post content. Only my home page RSS feed (https://lmyint.github.io/index.xml) had full content of posts.

Following the advice here by changing the outputs in config.toml to the TOML below did not fix the issue.

[outputs]
  home = [ "HTML", "CSS", "RSS" ]
  section = [ "HTML", "RSS" ]
  taxonomy = [ "HTML", "RSS" ]
  taxonomyTerm = [ "HTML", "RSS" ]

The fix: If you would like to contribute certain posts to a content aggregator that requires full post content on the RSS feed (such as R-Bloggers), do the following:

  1. Put these posts in one category (not tag)
  2. Go to https://gohugo.io/templates/rss/#the-embedded-rss-xml
  3. Look in the third row of the table: Taxonomy list in categories
  4. Create layouts/categories/category.rss.xml and use the default RSS template at the bottom of the page replacing
<description>{{ .Summary | html }}</description>

with

<description>{{ .Content | html }}</description>

After this, the RSS feeds for your category pages should have full post content.

Modifying the Contact section

By default, the Contact section of the page will display certain items in the params table of your config.toml file. With the TOML below, the Contact section would only contain my e-mail address.

[params]
  # Some other stuff...

  email = "lmyint@macalester.edu"
  address = ""
  office_hours = ""
  phone = ""
  skype = ""
  telegram = ""

I wanted to modify the Contact section to also show my Twitter handle, so I changed the TOML to the following.

[params]
  # Some other stuff...

  email = "lmyint@macalester.edu"
  address = ""
  office_hours = ""
  phone = ""
  skype = ""
  telegram = ""
  twitter = "lesliemyint"

I also had to update themes/hugo-academic/layouts/partials/widgets/contact.html. I duplicated the section of the HTML that displays the e-mail address parameter:

{{ with $.Site.Params.email }}
<li>
  <i class="fa-li fa fa-envelope fa-2x" aria-hidden="true"></i>
  <span id="person-email" itemprop="email">
  {{- if $autolink }}<a href="mailto:{{ . }}">{{ . }}</a>{{ else }}{{ . }}{{ end -}}
  </span>
</li>
{{ end }}

And I modified it to access the Twitter parameter ($.Site.Params.twitter), use the Twitter icon (class="fa-twitter"), and link to the Twitter website.

{{ with $.Site.Params.twitter }}
<li>
  <i class="fa-li fa fa-twitter fa-2x" aria-hidden="true"></i>
  <span>
  <a href="https://twitter.com/{{ . }}">{{ . }}</a>
  </span>
</li>
{{ end }}

Adding a CV

I use an HTML template for my CV and wanted to link to both the HTML and PDF versions.

First, I added a CV section to my top menu bar by adding the following TOML to config.toml:

[[menu.main]]
  name = "CV"
  url = "#cv"
  weight = 5

Next, I created a directory called cv/ within the content/ directory and added the HTML and PDF versions of my CV, index.html and cv.pdf respectively to content/cv/. Because my HTML CV relies on a stylesheet (cv.css), I added it to static/css/, and I link to it in index.html with the following:

<link type="text/css" rel="stylesheet" href="../css/cv.css">

The relative linking (../css/cv.css) looks as such because the directory structure that is generated in public/ looks like this:

|-public/
|---index.html
|---css/
|------cv.css
|---cv/
|------cv.pdf
|------index.html

Last, I created cv.md in content/home/ by duplicating the teaching.md file that comes with the theme by default. You can view my cv.md file on GitHub. The main hurdle in linking external resources is figuruing out the correct relative paths to these files. Again, looking at the generated directory structure above, we have to specify paths relative to index.html. So I include the following in cv.md.

My CV is available in [HTML](cv/) or [PDF](cv/cv.pdf) form.

Version control

My website is hosted with GitHub pages, and the associated repository only contains the file in the public directory of my Hugo project.

I used the Host on GitHub tutorial to figure out that the public directory can be set up as a git submodule within an enclosing git repository containing source files. The enclosing git repository for my website is available at: https://github.com/lmyint/personal_site.

comments powered by Disqus