No release in over a year
asciidoctor-bibtex is an Asciidocotor extension that adds bibtex support for AsciiDoc documents. It does so by introducing two new macros: `cite:[KEY]` and `bibliography::[]`. Citations are parsed and replaced with formatted inline text, and reference lists are automatically generated and inserted where the `bibliography::[]` macro is placed. The references are formatted using styles provided by CSL.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 5.11.0
~> 12.3.0

Runtime

 Project Readme

asciidoctor-bibtex: bibtex integration for AsciiDoc

GitHub Actions Status Latest Release

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.

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