Pandoc Citations

The Pandoc Citations are prefixed with the @ character. If the citation is @foo, that particular foo reference much be present in one of the specified bibliography files.

Users need to have the pandoc and pandoc-citeproc binaries1 present in the PATH.

When one or more citations are found by Pandoc, a top-level “References” section with matching references is automatically added at the very end of the post.

Enabling #

Pandoc based citation parsing is enabled by setting the #+hugo_pandoc_citations: keyword or :EXPORT_HUGO_PANDOC_CITATIONS: subtree property to t.

If a post has neither nocite meta-data, nor valid citation keys (@foo), the Pandoc parsing step is skipped even if the above Pandoc Citations parsing option is enabled.

Bibliography #

Bibliography files (example.bib) are specified using the #+bibliography: keyword or :EXPORT_BIBLIOGRAPHY: subtree property. It is mandatory to specify at least one bibliography file.

Multiple comma-separated bibliography files can be specified.

Note that the path to these bibliography files is relative to the Org file directory.

Nocite #

nocite is a special Pandoc-specific meta-data which can be used to add extra citations even when they are not referenced in the post. It is set like any other list-type custom front-matter parameter (i.e. :LIST_PARAM '(ELEMENT1 ELEMENT2)). See its example below.

link-citations is a special Pandoc-specific meta-data which, when set to true, enables linking of the citations in the post body to the corresponding reference in the “References” section. It is set like any other single-value custom front-matter parameter (i.e. :LIST_PARAM VALUE). See its example below.

Specifying Citation Style Language (CSL) #

By default, Pandoc uses Chicago Manual of Style author-date as the Citation Style Language (ref). This can be customized by using the Pandoc-specific meta-data csl to specify the new CSL file. It is set like any other single-value custom front-matter parameter (i.e. :LIST_PARAM VALUE). See its example below.

Note that the path to the CSL file is relative to the Org file directory.

Removal of Pandoc-specific meta-data #

The Pandoc-specific meta-data mentioned above (nocite, link-citations and csl) are auto-deleted from the front-matter in the final Markdown file that’s supposed to be used by Hugo.

Those meta-data were added using HUGO_CUSTOM_FRONT_MATTER only for Pandoc to parse. Also there’s no point leaking the user’s bibliography and CSL file paths in the front-matter to be processed by Hugo.

Example #

Here is a mini-example using Pandoc Citations:

* Citations Example
:EXPORT_FILE_NAME: citations-example
:EXPORT_BIBLIOGRAPHY: cite/bib/bib1.bib, cite/bib/bib2.bib
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :nocite '(@cite3 @cite4)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :link-citations true
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :csl cite/csl/my-custom-csl-format.csl
Here is a test example file with an in-text citation where someone
important says something important (e.g. @cite1). And here is
another bit of blah with a footnote citation.[fn:1]

* Footnotes

[fn:1] See [@cite2].
Above example assumes cite/bib/bib1.bib, cite/bib/bib2.bib and cite/csl/my-custom-csl.format.csl to exist in the same directory containing that Org file.

Search the ox-hugo test site for “citations” examples.

Also see Pandoc Manual – Citations for more details.

How Pandoc Citations work #

  1. ox-hugo first exports the Org file/subtree to a Markdown file as usual.
  2. pandoc then expands the @foo citations in that file and rewrites the whole Markdown file from the AST parsed by it.

  1. The Pandoc Citations feature was last tested on <2019-01-03 Thu> with Pandoc version 2.11.4. If you are running an older version, the quickest way to install might be to simply download the latest release archive from Pandoc releases, extract it and put the pandoc and pandoc-citeproc binaries in one of the directories in your PATH. ↩︎

Fork me on GitHub