📝 Easily manage your bibliography and in-text citations with Hugo, the popular static-site generator.

Documentation site + demo →

⚠️ Important note: APA is the only citation style currently available, and you must be aware that it does not match the entire APA spec.
More styles may be added eventually (contributions welcome!), but given that they are extremely verbose to implement, this is unlikely to happen in a near future.

Download Hugo Cite in the themes/hugo-cite directory, either by cloning with Git (the preferred method) or by downloading as a ZIP file.

The Git way:

git submodule add https://github.com/loup-brun/hugo-cite.git themes/hugo-cite

Your project directory should then look like this:

# Your Hugo project directory
├── config.yml
└── themes
    └── hugo-cite

Edit the theme parameter in your Hugo config file and add hugo-cite after your theme.

# config.yml
theme:
- <your-theme>
- hugo-cite

Reference the CSS somewhere in your HTML templates:

<link rel="stylesheet" type="text/css" href="{{ "/hugo-cite.css" | relURL }}" />

You must first provide a CSL-JSON bibliography file. (Other formats, such as BiBTeX, are not supported.) In Zotero for instance, this can be accomplished by selecting the CSL-JSON format when exporting a collection. Just include bib in the filename (such as bibliography.json,oh-my-bib.json, or simply bib.json) and save it inside your Hugo project directory.

Here is an example:

# Your Hugo project directory
├── content
│   ├── article1
│   │   ├── bib.json
│   │   └── index.md
│   ├── article2
│   │   ├── image.jpg
│   │   ├── index.md
│   │   └── mr-bib.json
│   └── article3
│       ├── index.md
│       └── oh-my-bib.json
└── path
    └── to
        └── bib.json

There are two shortcodes you can use in your content:

• {{< bibliography >}}: display a list of works.
• {{< cite >}}: render an in-text citation.

By default, the {{< bibliography >}} shortcode will render all entries from a bib.json included in a leaf bundle (see directory example above).

<!-- Markdown -->

{{< bibliography >}}

You can restrict the list only to works cited on the page (with the use of in-text citations, see below):

<!-- Markdown -->

{{< bibliography cited >}}

You can specify the path to a JSON file located inside the Hugo project directory in the content page’s front matter using the bibFile parameter. This is especially useful when working with cited entries:

---
title: My Article
bibFile: path/to/bib.json # path relative to project root
---

## Bibliography

<!-- The bibliography will display works from path/to/bib.json -->
{{< bibliography >}}

Alternatively, you can specify the path to the CSL-JSON file at the shortcode level:

<!-- Markdown -->

{{< bibliography "path/to/bib.json" >}}

You can also combine both options (the path to the JSON file must come first):

<!-- Markdown -->

{{< bibliography "path/to/bib.json" cited >}}

Note: if you are working with a cited bibliography, you’ll have to specify the path to the JSON file in the front matter for in-text citations to access the same file.

You can chose to use named params for clarity (the order does not matter here):

<!-- Markdown -->

{{< bibliography src="path/to/bib.json" cited="true" >}}

Thanks to Hugo’s getJSON function, the path can also be a URL.
Note however that this method may have some drawbacks if you are reloading often, see the Hugo docs regarding potential issues.

<!-- Markdown -->

{{< bibliography "https://example.com/my/bib.json" >}}

Use the {{< cite >}} shortcode to render rich in-text citations.

Example:

<!-- Markdown -->

{{< cite "Lessig 2002" >}}

The citation key (in the above example, Lessig 2002) must match the id field of a reference in your CSL-JSON file. You can make it look like an author-date format, or anything else.

Here’s an excerpt of a CSL-JSON file:

[
    {
        "id": "Lessig 2002",
        "author": [
            {
                "family": "Lessig",
                "given": "Lawrence"
            }
        ]
    }
]

Using the citation key defined in the CSL-JSON, you can reference your entry in content files:

<!-- Markdown -->

Our generation has a philosopher.
He is not an artist, or a professional writer.
He is a programmer. {{< cite "Lessig 2002" >}}

For an abbreviated in-text citation form, you can add a dash (-) at the beginning of your citation key:

<!-- Markdown -->

{{< cite "-Lessig 2002" >}}

The above would render (2002) rather than (Lessig, 2002).

You can also provide a page as the second positional parameter:

<!-- Markdown -->

{{< cite "Lessig 2002" 5 >}}

The example above will render (Lessig, 2002, p. 5) (note the p. was added by hugo-cite; you need not to add it).

You can instead specify a range of pages using a dash -, which will output pp. before the page range (ensure there is no space between the page numbers):

<!-- Markdown -->

{{< cite "Lessig 2002" 5-6 >}}

The example above will render (Lessig, 2002, pp. 5-6).

You can combine multiple citations in a single block, using the semi-colon (;) separator (no spaces around the semi-colon):

<!-- Markdown -->

{{< cite "Lessig2002;Nussbaum2011;Dewey1938" >}}

The above would render (Lessig, 2002; Nussbaum, 2011; Dewey, 1938).

Works with pagination too, in the matching order of the citation keys:

<!-- Markdown -->

{{< cite "Lessig2002;Nussbaum2011;Dewey1938" "5-6;;25" >}}

The above would render (Lessig, 2002, pp. 5-6; Nussbaum, 2011; Dewey, 1938, p. 25).

<!-- Include the list of cited works on the page -->
{{< bibliography cited >}}

Check out a working online demo →

WTFPL