Hugo Gotchas

This is a page to document lessons learned while making sites with the Hugo static site generator.

I have numbered these sections for reference.

By the way, you number sections with the following asciidoctor attributes just under the hugo header.

---
title: Hugo Gotchas
categories: ["Hugo"]
---
:sectnums:
:sectnumlevels: 5

1. Keep Separate Names for Content Directory Folder Names & Category Names

Apparently if you have the content directory folder names the same as your category names Hugo does not work well.

I have had repeated experiences with Hugo where the content directory folder name was "leadership" and a category name was "leadership" and the result was a blank screen.

I have not noticed this in Hugo’s documentation, but maybe I missed it.

Anyway, when you have different names, everything works great.

What Works

│   ├── lead_organizations
│   │   ├── MoreToCome.adoc
│   │   └── _index.adoc
│   ├── lead_self
│   │   ├── Influences_affecting_the_leadership_style_choice.adoc
│   │   ├── _index.md
│   │   └── liminal-thinking.adoc
│   ├── lead_teams
│   │   ├── _index.md
│   │   └── fast-decisions.adoc
│   ├── making-a-website
│   │   ├── 2019-11-02-hugo-gotchas.adoc
│   │   └── _index.adoc

2. Once You Set Your Content Folder Names Do NOT Change Them

Hugo uses the folder names in every single link.

If you move things after setup, you have to fix every link you break.

It is better to decide your folders up front and keep them that way.

3. Asciidoctor Footnote Differences (Book vs. Website)

In an asciidoctor book, you can have one footnote that is repeated throughout and only have the first instance show the code.

First Instance includes the text of the footnote.

footnote:OSLanhamResearch[Oran Stroud Lanham's Family History Research, October 1984.]

Then in later uses of the same footnote in a book, you can shrink it to a shortened form.

Later Instances are Short Form

footnote:OSLanhamResearch[]

But in Hugo, if it does not see a 1st instance that includes the text of the footnote WITHIN the scope of that page, then the footnote breaks.

So in Hugo, if you remember to add the full version footnote at the top of each page, then your footnotes work fine.

If you are converting an asciidoctor book to a website, then you have to remember to add these.

Updated on 02 Nov 2019