Skip to content

BibTeX and Citations

Jump to bottom Edit New page
Julian Barg edited this page May 20, 2021 · 6 revisions

Note: the behavior described on this page is only available on gollum v5.0 and higher

Summarized installation instructions (see below for details):

# Install Pandoc. For example on OS X:
brew install pandoc
# Install necessary gems:
gem install bibtex-ruby citeproc-ruby csl pandoc-ruby

Displaying BibTeX bibliography files

Gollum will recognise .bib as a valid extension for Pages in the wiki if you install the necessary rendering gems on your machine (i.e. gem install ...):

  • bibtex-ruby (for parsing BibTeX)
  • citeproc-ruby (for rendering the resulting citation info)
  • csl (for different citation styles)

Oneliner: gem install bibtex-ruby citeproc-ruby csl

Opening the relevant .bib in your browser will result in a rendered bibliography. You can also use the .bib file in combination with citations

Styles

The citation style used will default to CSL::Style.default. See https://citationstyles.org/ for general information.

You can specify a different style using YAML Metadata, either by pointing to a style file committed to the repository, or by naming a style contained in your CSL distribution:

csl: 'chicago-author-date.csl'

This will first look for a file 'chicago-author-date.csl' in the wiki and use that as a style file. If it cannot be found, gollum will look for a file by that name in your CSL distribution (by default installed under /usr/local/share/csl/).

Locales

Locales work the same as styles (see above), but use the locale: YAML key:

locale: 'locales-en-GB.xml'

Support for citations and footnotes through Pandoc

Using Pandoc as a renderer, gollum can render citations from .bib files, as well as footnotes, in Markdown documents (NB: for now, citations only work in Markdown pages). All you need to do is:

  • Install Pandoc
  • Install the pandoc-citeproc filter
    • e.g. on OS X: brew install pandoc-citeproc
    • ...but may already come with your Pandoc package by default
  • gem install pandoc-ruby

See here for information on citation and footnote syntax.

Set the bibliography file to use using YAML metadata:

bibliography: 'some.bib'

...where some.bib is the path to a BibTeX file committed to the repository. Gollum also supports a number of other citation-related metadata keys:

  • csl: as above
  • link-citations: make your citations hyperlinks to the corresponding bibliography entries (true or false)
  • nocite: BibTeX values added to this key will also be rendered in the bibliography, even if they are not cited in the page.

See here for more information on the link-citations and nocite options.

Placing citations in an entry

The syntax of the citeproc-ruby gem used by Gollum is based on pandoc's citation library. Assuming that a valid bib file is provided in the YAML Metadata, you can insert an in-text citation by writing the identified, preceded by an @a. For instance, @Einstein1905 will print as "Einstein (1905)". To wrap the citation in round brackets, surround it in square brackets: [@Einstein1905] will print as "(Einstein 1905)". Page numbers and other information that are placed in the square brackets will be printed inside the round brackets, too: [cf. @Einstein1905, 901] will print as "(cf. Einstein 1905, 901)". Note that there are some limitations on what characters can be used where. Notable, [cf. @Einstein1905, p. 901] will print as "(cf. Einstein 1905, 244)"--the p. is omitted.

Add a custom footer
Add a custom sidebar
Clone this wiki locally