Pandoc Citations

Org mode has built-in supporting for exporting citations starting version 9.5 . See Org Cite Citations for more info.

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 executable1 present in the PATH.

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 added using HUGO_CUSTOM_FRONT_MATTER only for Pandoc to parse.

Once they are used by pandoc, those front-matter keys are deleted in the final Markdown file (Hugo has no use of those Pandoc-specific front-matter keys).

Auto-insertion of headings #

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

By default, ox-hugo will insert a Markdown heading with the string defined in org-hugo-pandoc-cite-references-heading before that Pandoc-inserted References section. It’s default value is References {#references}".

If you want to prevent this Markdown heading auto-insertion, set this variable to an empty string ("").

Example #

Here is a small 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].
Code Snippet 1: Example of using Pandoc Citations
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 the Org file.

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 with Pandoc version 2.16.2. 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 executable in one of the directories in your PATH↩︎

Fork me on GitHub