Image Title "Untitled" by Tom Hermans is licensed under Unsplash.

Hugo Footnotes and Citations

GeekThis remains completely ad-free with zero trackers for your convenience and privacy. If you would like to support the site, please consider giving a small contribution at Buy Me a Coffee.

Adding citations and footnotes to your articles benefits your readers, adds additional credibility to your article, and can help improve your website’s SEO1. 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.

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.


  1. https://blog.alexa.com/outbound-links-content-marketing/ ↩︎

Related Posts

Pack of Shortcodes for Hugo

A free download of new shortcodes for your Hugo blog and website. Add new custom shortcodes to Hugo quick and easily.

Generating Random Numbers, Strings, and more in Hugo

Create random numbers, random strings, fetch random items in slices, and generate repeatable seeds within the Hugo static site generator.

How to Separately Handle Multiple Website Deployments

Learn how to configure your computer to run multiple website deployments with rsync and multiple Linux accounts.

Build Script for Hugo Websites

A basic bash build script for Hugo websites to compress images, JavaScript files, and CSS before releasing your website to the public. Keeps a copy of uncompressed assets while easily compressing all files before uploading your website.