How to Create a Website with Hugo Academic Theme: Useful Tips

This post contains an assortment of sections that provide some useful information about how to adjust certain things on the site or just generally how to make life easier when working with Hugo or the Academic theme. Essentially, it documents many of the miscellaneous changes I made to produce my current website. Additionally, you can access the GitHub repo for the Academic theme with my modifications here.

“See all” button

If you started adding more than five (the default count param that’s set in front matter for the pages widget used on the homepage) posts or publications, you’ll notice a “See all posts” or “See all publications” button (really just a link) that appears in these sections on the homepage. These links allow the user of your website to navigate to the appropriate section pages (e.g. domain.com/post) directly from the homepage - a useful feature! By default, this button will only show up when the total number of items you have in that section is greater than the count that’s set in the front matter, which determines how many items are shown. Since I prefer to have the section pages always accessible, I modified the code in the pages widget partials template. At the end of the pages.html file you’ll see,

{{ if gt $count $items_count }}
<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>
{{ end }}

Notice the line {{ if gt $count $items_count }}? That’s what we’ll want to remove, along with the corresponding {{ end }}, in order to show the “See all” link. So what you’re left with should look like,

<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>

If you want to also add this feature to the portfolio widget that’s used for the projects section, there’s more work to do. In the same layouts/partials/widgets folder you’ll want to open up portfolio.html. At the top of the file, right after the {{/* Initialise */}} section you’ll want to add,

{{/* Localisation */}}
{{ $i18n := "" }}
{{ if eq $items_type "project" }}
  {{ $i18n = "more_projects" }}
{{ else }}
  {{ $i18n = "more_pages" }}
{{ end }}

{{/* Query */}}
{{ $archive_page := site.GetPage "Section" $items_type }}

which define some variables we will be using. Next, at the bottom of the file, right after the <div> section that uses the partials, you’ll want to add,

<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>

This should look familiar, since it’s the same code as the one you saw just before in pages.html. The $archive_page.RelPermalink is the URL to the section page, so in this case domain.com/publication and the $i18n variable allows you to customize the text used for the link. It does this with the i18n function that I’ll explain in the next section.

i18n

For a bit of background on internationalization and localization, aka i18n, you can check out the Wikipedia page on it, but it’s basically just a simple translation module In any case, it’s not necessary since I’ll tell you exactly what you’ll need to do. First navigate to the directory named i18n in the theme repo and open the en.yaml file, which provide the translation for English phrases. You’ll see a section for “Pages widget” that looks something like,

# Pages widget

- id: more_pages
  translation: See all

- id: more_posts
  translation: See all posts

- id: more_talks
  translation: See all talks

- id: more_publications
  translation: See all publications

we just need to add an additional entry like so,

- id: more_projects
translation: See all projects

to process the new more_projects argument. It actually doens’t matter where in the file you add these lines, but you should probably do it in the same section just for organazational reasons. If you run accross i18n again in the templates, remember this file, as it’ll likely be the answer to your problem.

Format post dates

For those of you that plan on having a few posts on your site, you may have noticed that the “last updated on” dates for your posts are wrong - everything shows up as being modified on the current date. Don’t worry, this is a known problem, as you can see from this GitHub issue. It turns out this is actually a bug on the side of Netlify, how your website is being hosted, rather than the Academic theme. However, this fix is super simple, you just need to change HUGO_ENABLEGITINFO = "true" to HUGO_ENABLEGITINFO = "false" in the netlify.toml file in the root directory of your website repo. After this modification, the dates should now correctly reflect what the date and lastmod params that are set in the front matter for each post.

I also ended up doing an additional modification to how the dates appeared after this fix in order to show both the original publish date as well as the last updated date. However, this is mainly a matter of personal preference so please feel free to skip the rest of this section if you’re not interested in making this change. The code that’s used to create the published/modified dates can be found in layouts/partials/page_metadata.html within the theme repo. I’ve extracted the relevant part for you here,

<span class="article-date">
    {{ $date := $page.Lastmod.Format site.Params.date_format }}
    {{ if eq $page.Type "publication" }}
      {{ $date = $page.Date.Format (site.Params.publications.date_format | default "January, 2006") }}
    {{ else }}
      {{ if ne $page.Params.Lastmod $page.Params.Date }}
          {{ i18n "last_updated" }}
      {{ end }}
    {{ end }}
    {{ $date }}
</span>

If you study the code you’ll see that $date is what will ultimately be shown on the page and it is set to the lastmod date ($page.Lastmod). Additionally, with the code

{{ if ne $page.Params.Lastmod $page.Params.Date }}
  {{ i18n "last_updated" }}
{{ end }}

it will add the “Last updated on” text in front of the date if the last modified date is not equal to the publish date. Since, I planned to also show the original publish date and didn’t want it to get too long I decided to edit the i18n/en.yaml file to change the translation of “last_updated” from “Last updated on” to just “Last updated”.

- id: last_updated
  translation: Last updated

To get both dates shown, you’ll want to add a couple lines to the code between the <span> tags. If you just want the solution, the end result should look something like this:

<span class="article-date">
    {{ $lastmod := $page.Lastmod.Format site.Params.date_format }}
    {{ $date := $page.Date.Format site.Params.date_format }}
    {{ if eq $page.Type "publication" }}
      {{ $date = $page.Date.Format (site.Params.publications.date_format | default "January, 2006") }}
    {{ else }}
      {{ if ne $page.Params.Lastmod $page.Params.Date }}
          {{ i18n "last_updated" }}
          {{ $lastmod }} |
      {{ end }}
    {{ end }}
    Published {{ $date }}
</span>

And that’s it, you’re done.

Author list tips

Highlight superuser

If you want to bold your name when it appears in the author list (e.g. for publications) there’s an simple setting in config/_default/params.toml to do this: highlight_superuser = true. However, there a few caveats about this method. In order for this to work, you’ll need to use the authors username that’s set in the user profile for the superuser. By default this will be admin, which you can see in content/authors/admin/_index.md. When you do this, the name that appears in the author list will be what is set in the title field of the same file. Since this display name is used on things like the homepage about widget, it is probably set to your full name. However, if you want to use something different (like first initial last name, which is common for pubications) it is not straightforward with this approach.

Therefore, I’ll show you another way to format the author names that offers more flexibility. In layouts/partials/page_metadata_authors.html you’ll need to replace {{ $name }} with {{ $name | markdownify }}, which format the names using Markdown syntax. At the time of writing, there are two locations where this occurs. After this you can use "**YOURNAME**" in the authors front matter variable to make it bolded. Note: make sure you include the quotes. This makes it super easy to format any author name however you want.

Author notes

If you want to add asteriks to indicate “equal contribution” or whatever else you can make use of the author_notes in the front matter. By setting these author notes it’ll add a symbol after the author’s name. The notes correspond exactly to the authors list, i.e. the first note for the first author, second for the second author, etc. To change the symbol that’s used, change the line <span title="{{.}}" class="author-notes">(?)</span> in layouts/partials/page_metadata_authors.html, replacing (?) with what you want (I use *).