asciidoctor-bibliography

= Citations and Bibliography the "asciidoctor-way"

asciidoctor-bibliography lets you handle citations and bibliography in http://asciidoctor.org/[asciidoctor].

image:https://github.com/riboseinc/asciidoctor-bibliography/actions/workflows/rspec.yml/badge.svg["Build Status", link="https://github.com/riboseinc/asciidoctor-bibliography/actions/workflows/test-and-release.yml"] image:https://img.shields.io/gem/v/fontist.svg["Gem Version", link="https://rubygems.org/gems/fontist"] image:https://img.shields.io/github/issues-pr-raw/riboseinc/asciidoctor-bibliography.svg["Pull Requests", link="https://github.com/riboseinc/asciidoctor-bibliography/pulls"] image:https://codeclimate.com/github/riboseinc/asciidoctor-bibliography/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/asciidoctor-bibliography"]

== Introduction

This gem allows you to add citations to AsciiDoc imported from BibTex files.

Citation styling leverages the popular http://citationstyles.org/[CSL] language so you have direct access to thousands of crowdsourced styles including IEEE, APA, Chicago, DIN and ISO 690.

The bibliography::[] command generates a full reference list that adheres to your configured citation style.

On top of that you also have a formatter derived from the Bib(La)TeX world, so all the macros you are familiar with are recognized.

Its syntax is designed to be "native-asciidoctor":

• single cite cite:[key];
• contextual cite cite[key, page=3];
• multiple cites cite:[key1]+[key2];
• full cite fullcite:[key]; and
• TeX-compatible macros including citep:[key], citet:[key] and friends.

== Installation

Add this line to your Gemfile:

[source,ruby]

gem "asciidoctor-bibliography"

And then execute:

[source,console]

$ bundle install

Or install it yourself as:

[source,console]

$ gem install asciidoctor-bibliography

== Quick start

In your document header, choose the filename of a BibTeX database and a style (e.g. apa, ieee, nature and http://editor.citationstyles.org/searchByName/[others]).

[source,asciidoc]

= My first document using asciidoctor-bibliography :bibliography-database: my_database.bib :bibliography-style: apa

In your document body, cite your resources using their keys:

[source,asciidoc]

This will end with a citation cite:[Aa2017].

Then list out the resources you cited:

[source,asciidoc]

bibliography::[]

When compiling, include asciidoctor-bibliography in your chain:

[source,console]

$ asciidoctor -r asciidoctor-bibliography my_first_document.adoc

That's it!

== Usage

asciidoctor-bibliography allows for more customizations and macros. Let's examine all its features in full detail.

=== Citations

To cite a resource you provide its unique database key to an inline macro:

[source,asciidoc]

Here comes a citation cite:[Aa2017] and it's gone.

Referring to a specific location inside a resource can be done providing an extra named attribute:

[source,asciidoc]

cite:[Aa2017, page=42]

Allowed locators are book, chapter, column, figure, folio, issue, line, note, opus, page, paragraph, part, section, sub-verbo, verse and volume. Their support depends upon which ones your style implements.

An extra locator attribute with no custom rendering exists. It appears where the ordinary locators would, but you can fully customize it:

[source,asciidoc]

cite:[Aa2017, locator=" halfway through"]

Note that all locators except the first one will be ignored.

To prefix and suffix citations with arbitrary strings you can use the relative attributes:

[source,asciidoc]

cite:[Aa2017, prefix="see ", suffix=" if you will"]

You can replace the rendered citation with arbitrary text or interpolate it directly:

[source,asciidoc]

cite:[Aa2017, text="replacement text"] // the next two lines are equivalent: cite:[Aa2017, prefix="see ", suffix=" if you will"] cite:[Aa2017, text="see {cite} if you will"]

To cite multiple resources you concatenate them as follows:

[source,asciidoc]

cite:[Aa2017]+[Bb2017]+[Cc2017]

You can apply a different locator to each one.

IMPORTANT: when using a prefix, suffix or text containing ] (the right square bracket character) remember to escape it as the corresponding HTML sequence ]. E.g.: cite:[Foo2019, text="see {cite} or [this] perhaps"].

=== Bibliographies

To render the bibliography you simply use the following block macro:

[source,asciidoc]

bibliography::[]

You can handle multiple bibliographies by providing a target parameter to citation macros:

[source,asciidoc]

cite:foo[Aa2017]+bar[Bb2017]

You can then render all citations targeting a specific bibliography by using the target parameter again:

[source,asciidoc]

Index of Foos

bibliography::foo[]

Index of Bars

bibliography::bar[]

Giving no target is equivalent to using default as a target.

=== Databases

Specifying a database file is mandatory and it can be done in the header with its filename:

[source,asciidoc]

:bibliography-database: my_database.bib

Currently only the BibTeX format is supported, with .bib or .bibtex extensions.

BibLaTeX databases can be used too, but only the subset of features belonging to BibTeX are safe to use: unknown attributes will be silently ignored. If the file has .biblatex extension the you will receive a warning on compilation.

If you need to include multiple databases, you can simply list their names. Wildcards are allowed too:

[source,asciidoc]

:bibliography-database: db1.bib db2.bib ../dbs/*.bibtex

=== Styling

The default style for citations and bibliographies is apa. You can change that in the header:

[source,asciidoc]

:bibliography-style: apa

Valid style names can be found directly in the https://github.com/citation-style-language/styles[official repository] or searching through the friendly http://editor.citationstyles.org/[style editor].

You can also simply use the filename of a CSL file on your machine if you need more customization.

=== Localization

Citation styles can be localized using the following option:

[source,asciidoc]

:bibliography-locale: en-US

The default is en-US. Here is an exhaustive list of recognized locales: af-ZA, ar, bg-BG, ca-AD, cs-CZ, cy-GB, da-DK, de-AT, de-CH, de-DE, el-GR, en-GB, en-US, es-CL, es-ES, es-MX, et-EE, eu, fa-IR, fi-FI, fr-CA, fr-FR, he-IL, hr-HR, hu-HU, id-ID, is-IS, it-IT, ja-JP, km-KH, ko-KR, lt-LT, lv-LV, mn-MN, nb-NO, nl-NL, nn-NO, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sl-SI, sr-RS, sv-SE, th-TH, tr-TR, uk-UA, vi-VN, zh-CN and zh-TW.

=== Hyperlinks

By default, citations include hyperlinks to their entry in the bibliography. You can disable them in the header:

[source,asciidoc]

:bibliography-hyperlinks: false

=== Sorting

You can override the sorting specified by the CSL style you have chosen, if you desire to do so.

The relevant option is bibliography-sort and it accepts a YAML string specifying a list of keys to sort the entries with.

Let's explore some of the possibilities.

==== No Sort

The simplest option is no sorting; an empty list will cause the entries to be in appearance order.

[source,asciidoc]

:bibliography-sort: []

==== Sort By Single Key

To sort in a single key - say, the rendered author name - it's as simple as

[source,asciidoc]

:bibliography-sort: macro: author

==== Reverse Sort

However you might want to reverse the order:

[source,asciidoc]

:bibliography-sort: { macro: author, sort: descending }

==== Sort By Multiple Keys

It is possible to use any number of sorting keys putting them in an array. E.g. to sort by issuing date:

[source,asciidoc]

:bibliography-sort: [{ macro: author, sort: descending }, { variable: issued }]

You might be asking: what is the difference between variable s and macro s?

The former are metadata fields fixed by the http://docs.citationstyles.org/en/stable/specification.html#appendix-iv-variables[CSL specification].

The latter are combinations of variables defined by your chosen style.

To use them effectively you'll need to know its implementation.

This task is not daunting at all, as the http://editor.citationstyles.org/[style editor] allows you to quickly list them and understand their role.

As for the sort option, the valid values are ascending (default) and descending as you'd expect.

=== TeX-mode

While the cite macro is reserved for CSL styling and works with thousands of styles, the traditional Bib(La)TeX macros are also implemented with their usual names and can be used with a few styles:

• citet (in LaTeX world \citet is equivalent to \cite)
• citet*
• citealt
• citealt*
• citep
• citep*
• citealp
• citealp*
• citeauthor
• citeauthor*
• citeyear
• citeyearpar
• nocite

To cite multiple items you can concatenate them just like with cite.

IMPORTANT: The nocite macro does not provide an equivalent to the ordinary TeX wildcard notation \nocite{*} to print all references.

All macros accept standard locators, locator, suffix and prefix. The behaviour of these parameters is designed to reproduce the one expected from the traditional TeX citation macros \cite...[prefix][suffix]{key}.

You can set their style in the header:

[source,asciidoc]

:bibliography-tex-style: authoryear

Accepted values are authoryear (default) and numeric.

IMPORTANT: The cite macro and the cite... macros described in this section are completely independent mechanisms. The former, along with the bibliography, is styled with :bibliography-style: (thousands of styles available) while the latter is styled with with :bibliography-tex-style: (much more limited, only has the styles listed above).

The macro fullcite is also available and accepts no parameters except a single reference key. Unlike its siblings, it is able to render CSL styles and is configured using :bibliography-style:.

==== Advanced options

When rendered citations (used at the beginning of a line) or references start with a special character, it might throw off asciidoctor. To avoid this an {empty} is prepended by default. Using the bibliography-prepend-empty you can decide whether to prepend it to citations (citation), references (reference), both (true) or neither (false). Default is true.

[source,asciidoc]

:bibliography-prepend-empty: true

Sometimes it is desirable to wrap the rendered citations in a passthrough. Using the bibliography-passthrough you can decide whether to wrap citations (citation), references (reference), both (true) or neither (false). They are wrapped in an inline passthrough (+++). Default is false.

[source,asciidoc]

:bibliography-passthrough: false

==== CLI usage

All header attributes described above can also be passed through the commandline as is customary. E.g.:

[source,console]

$ asciidoctor -r asciidoctor-bibliography -a bibliography-style=ieee my_first_document.adoc

Values given in such way will take highest priority.

== Development

We follow Sandi Metz's Rules for this gem, you can read the https://thoughtbot.com/blog/sandi-metz-rules-for-developers[description of the rules here]. All new code should follow these rules. If you make changes in a file that already violates these rules, you should fix the violations as part of your contribution.

=== Setup

Clone the repository.

[source,sh]

git clone https://github.com/riboseinc/asciidoctor-bibliography

Setup your environment.

[source,sh]

bin/setup

Run the test suite

[source,sh]

bin/rspec

== Contributing

First, thank you for contributing! We love pull requests from everyone. By participating in this project, you hereby grant https://www.ribose.com[Ribose Inc.] the right to grant or transfer an unlimited number of non exclusive licenses or sub-licenses to third parties, under the copyright covering the contribution to use the contribution by all means.

Here are a few technical guidelines to follow:

1. Open an https://github.com/riboseinc/asciidoctor-bibliography/issues[issue] to discuss a new feature.
2. Write tests to support your new feature.
3. Make sure the entire test suite passes locally and on CI.
4. Open a Pull Request.
5. https://github.com/thoughtbot/guides/tree/main/git#write-a-feature[Squash your commits] after receiving feedback.
6. Party!

== Credits

This gem is developed, maintained and funded by https://www.ribose.com[Ribose Inc.]

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].