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.

Enabling #

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

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 #

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
:PROPERTIES:
:EXPORT_FILE_NAME: citations-example
:EXPORT_HUGO_PANDOC_CITATIONS: t
: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
:END:
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].

Note

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.