asciidoctor-bibtex adds bibtex support for asciidoc documents by introducing
two new macros: cite:[KEY]
and bibliography::[]
. Citations are parsed and
replaced with formatted inline texts, and reference lists are automatically
generated and inserted into where bibliography::[]
is placed.
asciidoctor-bibtex is designed to be used as an extension to asciidoctor, although it supports asciidoc to asciidoc transformation at the moment. Thus this extension can be used together with other asciidoctor extensions such as asciidoctor-mathematical and asciidoctor-pdf to enrich your asciidoc experience.
asciidoctor-bibtex starts as a fork of asciidoc-bib and goes along a different way. The major reason for the fork at the time was the differences in citation and bibliography macros. asciidoc-bib failed to follow the grammar of macros in asciidoc, thus to avoid breaking existing documents, a fork is inevitable. Other reasons include the inability to use asciidoctor arguments in asciidoc-bib.
While asciidoc-bib focuses on replacing citations in the original documents and produces new asciidoc documents, asciidoctor-bibtex focuses on compatibility with asciidoctor and other asciidoctor extensions at the very beginning. As time passes, asciidoctor-bibtex diverges significantly from its ancesstor. For example, asciidoctor-bibtex now supports generating real bibtex ciations and bibliography, so it can be used together with asciidoctor-latex for native bibtex support.
gem install asciidoctor-bibtex
asciidoctor-bibtex depends on bibtex-ruby, citeproc-ruby and csl-styles. (Ensure 'ruby-dev' and 'libxslt1-dev' are installed, so the dependencies will compile.)
asciidoctor must also be installed for 'asciidoctor-bibtex' to work. asciidoctor version 1.5.2 or higher is required.
Syntax for inserting a citation is the following inline macro:
cite|citenp:[ref(pages), ...]
where '(pages)' is optional.
Examples of "chicago-author-date" style:
cite:[Lane12]
becomes "(Lane 2012)"citenp:[Lane12]
becomes "Lane (2012)"cite:[Lane12(59)]
becomes "(Lane 2012, 59)"
For apa (Harvard-like) style:
cite:[Lane12]
becomes "(Lane, 2012)"citenp:[Lane12]
becomes "Lane (2012)"cite:[Lane12(59)]
becomes "(Lane, 2012, p.59)"
For ieee, a numeric style:
cite:[Lane12,Lane11]
becomes "[1, 2]"
To add a list of formatted references, place bibliography::[]
on a line by itself.
Attribute Name | Description | Valid Values | Default Value |
---|---|---|---|
bibtex-file | Bibtex database file | any string, or empty | Automatic searching |
bibtex-style | Reference formatting style | any style supported by csl-styles | ieee |
bibtex-order | Order of citations | appearance or alphabetical |
appearance |
bibtex-format | Formatting of citations and bibliography | asciidoc or bibtex or biblatex |
asciidoc |
Use asciidoctor-bibtex as an extension:
asciidoctor -r asciidoctor-bibtex sample.adoc
The files within this project may be distributed under the terms of the Open Works License: http://owl.apotheon.org
See https://github.com/petercrlane/asciidoc-bib for the original asciidoc-bib.