Skip to content

Add bibtex citation support for asciidoc documents

License

Notifications You must be signed in to change notification settings

asciidoctor/asciidoctor-bibtex

Repository files navigation

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.