asciidoctor-bibtex: bibtex integration for AsciiDoc

asciidoctor-bibtex adds bibtex integration to AsciiDoc documents by introducing three new macros: cite:[KEY], bibitem:[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. bibitem:[KEY] will insert a rendered bibliography item directly into the text.

asciidoctor-bibtex is designed to be used as an extension to Asciidoctor. Thus this extension can be used together with other asciidoctor extensions such as asciidoctor-mathematical and asciidoctor-pdf to enrich your AsciiDoc experience.

Note	asciidoctor-bibtex no longer supports AsciiDoc-to-AsciiDoc conversion.

History

asciidoctor-bibtex starts as a fork of asciidoc-bib and goes along a different path. 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 and thus caused problems with existing documents and extensions. Thus, a fork was needed. Another reason was the inability to pass configuration via AsciiDoc attributes.

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 citations and bibliography, so it can be used together with asciidoctor-latex for native bibtex support.

Install

$ gem install asciidoctor-bibtex

asciidoctor-bibtex depends on bibtex-ruby, citeproc-ruby, and csl-styles. Ensure the ruby-dev and libxslt1-dev packages are installed on your machine so the dependencies will compile properly.

Asciidoctor must also be installed for 'asciidoctor-bibtex' to work. Asciidoctor version 2.0.0 or higher is required.

Usage

First, you need to have a valid bibtex file. You specify the location to this file using the bibtex-file document attribute.

Macros

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.

One can use bibitem:[Lane12] to insert a rendered bibliography item inline, maybe to generate a cv. For example:

= My CV

== Publications

=== 2019

- bibitem:[Me2019a]
- bibitem:[Me2019b]
- bibitem:[Me2019c]

Configuration

Configuration is applied in the form of AsciiDoc document attributes, which must be defined in the document header.

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`, `bibtex` or `biblatex`	`asciidoc`
bibtex-locale	Locale used to render the bibliography	strings supported by CSL	`en-US`
bibtex-throw	Throw an error on unknown references	`true` or `false`	`false`
bibtex-citation-template	Custom citation template for numeric style	Any string matching `/(.?)\$id(.)/`	`[$id]`

Commandline

Use asciidoctor-bibtex as an extension with the CLI:

$ asciidoctor -r asciidoctor-bibtex sample.adoc

License

The files within this project may be distributed under the terms of the Open Works License.

Links

See https://github.com/petercrlane/asciidoc-bib for the original asciidoc-bib source.