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

Hugo Footnotes and Citations

Our site remains ad-free thanks to our affiliates. This post's featured affiliate is Robinhood. Robinhood has commission-free investing, and tools to help shape your financial future. Sign up and get your first stock free.

The post is not sponsored by the above affiliate and the content here is not representative of their company.

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.

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.

Get Hugo to Show Content from Multiple Sections

Learn how to combine posts from multiple sections into a single list and range inside of Hugo. Show content from two or more sections in a single list.