Hugo Footnotes and Citations

Adding citations and footnotes to your articles benefits your readers, adds additional credibility to your article, and can help improve your website’s SEO¹. With Hugo, it’s really simple to add footnotes to your articles without any additional configuration or code.

Hugo has two main Markdown parsers that it uses. Versions 0.60 and later use Goldmark while previous versions use BlackFriday. Both of these parsers support footnotes without any additional configuration and will add the footnotes to the bottom of the post automatically.

Adding a Footnote

The syntax for footnotes in Markdown is similar to the syntax used to create reference-style links in Markdown. The name of the footnote (denoted inside the square brackets) can be set to anything, but the parser will render your citations as incrementing numbers.

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

The footnote can contain text and links. This makes it easy to fit your citation style guide. Footnotes can also contain block elements such as paragraphs. This is done by indenting lines within a footnote with 4 spaces or a tab.

Stylizing Citations and Footnotes

Goldmark and BlackFriday both render footnotes similarly. Below is the HTML output of a footnote that has been rendered. To modify the appearance of footnotes, you’ll want to change your CSS to modify how links with a.footnote-ref appear, along with how the block div.footnotes appears.

<p>
	That's some text with a footnote.
	<sup id="fnref:1">
		<a href="#fn:1" class="footnote-ref" role="doc-noteref">1</a>
	</sup>
</p>

<div class="footnotes" role="doc-endnotes">
	<hr />
	<ol>
		<li id="fn:1" role="doc-endnote">
			<p>
				And that's the footnote.
				<a href="#fnref:1" class="footnote-backref" role="doc-backlink">&#8617;</a>
			</p>
		</li>
	</ol>
</div>

The default rendering of footnotes should work well if horizontal lines and typography have been styled. There is no easy way to change how the HTML is rendered for footnotes at the moment. CSS can be rather powerful and you can use a lot of techniques to get to where you need to be.

Adding Brackets around Footnote Links

I prefer the appearance of brackets around the footnote links within the content. Displaying only the number looks more like a bug than a reference. To add brackets around links, we use some CSS tricks to add content before and after the link element.

a.footnote-ref::before {
    content: '[';
}

a.footnote-ref::after {
    content: ']';
}

Footnote Settings

Depending on whether you use Goldmark or BlackFriday, there are a few options you can set within your Hugo config file to affect footnotes. Don’t get too excited as it’s very limited on the amount of configuration possible.

Goldmark

The settings for Goldmark are limited to simply enabling or disabling footnotes. In the future, it’s my suspicion that render hook templates will support footnotes, but that’s just a wild guess.

markup:
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      footnote: true

BlackFriday

BlackFriday has some additional configuration, but it’s still very limited in ways to customizing the rendering of footnotes.

markup:
  defaultMarkdownHandler: blackfriday
  blackFriday:
    footnoteAnchorPrefix: ""
    footnoteReturnLinkContents: ""

footnoteAnchorPrefix is added to footnote links to ensure uniqueness. Instead of links pointing to #fnref:1 they will point to #fnref:<prefix>1.

footnoteReturnLinkContents changes the contents of the link in the footnote section that links back to the content in the article. By default, this value is <sup>[return]</sup>. The value is rendered as-is, including HTML.