-
Notifications
You must be signed in to change notification settings - Fork 1.6k
BibTeX and Citations
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
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
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 work the same as styles (see above), but use the locale:
YAML key:
locale: 'locales-en-GB.xml'
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
- e.g. on OS X:
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
orfalse
) -
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.
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.