This article describes Hugo shortcodes to manage citations and include bibliographies on a Hugo website using a CSL JSON file.

Create Bibliographies in Hugo with a shortcode

Peter Prevos

Peter Prevos |

899 words | 5 minutes

Share this content

All writers stand on the shoulders of giants. To recognise that fact, academic writing uses a comprehensive system of citations and bibliographies to acknowledge the authors whose ideas you have based your work. Unfortunately, there is no standardised method in Hugo to manage citations and bibliographies. This article shows how to manage a Hugo bibliography using a CSL-JSON file and shortcodes.

The code for these shortcodes forms part of the Third Hemisphere Hugo theme, which is used for this website. You can download the code from GitHub:

CSL JSON Bibliography files

Hugo can generate HTML content from JSON files, so all we need is a bibliography in this format. The Citation Style Language (CSL) is a modern bibliography format that is perfect for developing Hugo shortcodes.

You can create CSL JSON with your favourite bibliography manager, such as Zotero or Mendeley. In Zotero you can use the Better BibTeX package to synchronise your Zotero database to a JSON file. You can also export BibTeX files to JSON with Pandoc:

pandoc filename.bib -t csljson -o filename.json

The bibliography lives in the data folder of your website. for example data/example.json. These shortcodes don't work for data files stored in the theme's data folder.

The Hugo Bibliography Shortcodes

The Third hemisphere Hugo theme contains three shortcodes to display information from the bibliography file:

  • Citation (cite)
  • Bibliography (bibliography)
  • Bibliography length (bib-length)

You need to set a default JSON bibliography file by defining the bib page variable in the front matter of the each page that uses this data to the relevant JSON filename, without extension, which Emacs org mode is #+bib: example and in YAML:

---
params:
  bib: example
---

The Citation Style Language specifies over thirty reference types. These Hugo shortcodes only parse the most common types:

  • Books
  • Book chapters
  • Conference papers
  • Journal articles
  • Reports
  • Theses

Citations

The citations shortcode can create three types of citations. Two types of author-year citations and a full bibliographical citation. The cite shortcode takes two variables, the citation type (p, t or f) and the citation key. These shortcodes can only cite a single entry.

Textual citations

Textual citations follow the author-year system. When there are more than one author or editor, the names are combined with "and". If there are more than two authors or editors, the first two are named, followed by "et al.". When no author or editor is defined, it displays "Anonymous". In the next part, the code displays the year of the publication between parentheses.

The letter p or t are used to indicate parenthetical or textual citations, for example:

The taste of tap water influences perceptions of quality {{< cite p teillet-2010 *>}} and {{< cite t burns-2011 >}} suggested that … results in:

"The taste of tap water influences perceptions of quality (Teillet et al. 2010) and Burns et al. (2011) suggested that …"

Using a file or cite key that does not exist causes an error: Entry not found.

 

Full citations

The {{< cite f zoeteman-1980 >}} gives the full citation in APA style, for example: "Zoeteman (1980). Sensory Assessment of Water Quality. Pergamon Press."

The first part is the same as a textual citation. The remainder of the citation depends on the type as shown in the table below:

Type Citation field names
Article title. container-title, volume (issue), page.
Book title. publisher.
Chapter title. In: editor (Ed.), container-title. publisher.
Conference title, event-name (event-location).
Report title, (number). publisher.

If the DOI field is available, it will be added to the end of the citation as a hyperlink. The URL field is used when the DOI is not defined.

 

List of references

The {{< bibliography >}} shortcode lists the literature stored in the referenced JSON file. The entries are displayed in the order in which they appear in the JSON file.

The example bibliography contains 5 entries, one of each of the supported reference types.

Burns, Ann V. et al. (2011). Victorian Water Customer: Water Services Needs & Values Summary Report. Victorian Water Customer: Water Services Needs & Values Summary Report, (Report 1).Accenture.

Mays, Larry W. and Angelakis, Andreas Nikolaos (2012). Ancient gods and godesses of water. In: Angelakis et al. (Eds.), Evolution of Water Supply Throughout the Millennia (IWA, London).

Teillet, Eric et al. (2010). Sensory methodologies and the taste of water. Food Quality and Preference, 21(8), 967–976.doi: 10.1016/j.foodqual.2010.04.012.

Webber, Michael A. et al. (2014). When does the taste of water become offensive? In: OzWater, Brisbane.

Zoeteman, B. C. J. (1980). Sensory Assessment of Water Quality. Pergamon Press.

You can filter the bibliography by adding a keyword, for example: {{< bibliography tast >}}. Any entry where the keyword appears in the keyword field is displayed (normalised to lowercase). The query matches on the start of the keyword, so this example shows any entry where the keyword field includes taste or tasting.

Lastly, the {{< bib-length >}} shortcode counts the number of entries in the bibliography file and displays it as a number.

Hugo Bibliography Shortcodes

These shortcodes are not yet fully optimised, but good enough to share with the world. I use them on my website about scientific research into theatrical magic. These are some of the improvements I like to make:

  • Cite multiple entries in one shortcode call
  • Add prefix and suffix numbers to citations
  • Reference multiple bibliography files
  • Add more literature types

The source code for these shortcodes is available on GitHub.

Share this content

You might also enjoy reading these articles

Hugo SEO plugin: A Search-Engine Optimisation partial template

Create Websites with Emacs: Blogging with Org mode and Hugo

Export WordPress to Hugo Markdown or Org Mode with R