asciidoctor-bibliography
Advanced tools
= 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":
cite:[key];cite[key, page=3];cite:[key1]+[key2];fullcite:[key]; andcitep:[key], citet:[key] and friends.== Installation
Add this line to your Gemfile:
And then execute:
Or install it yourself as:
== 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]).
In your document body, cite your resources using their keys:
Then list out the resources you cited:
When compiling, include asciidoctor-bibliography in your chain:
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:
Referring to a specific location inside a resource can be done providing an extra named attribute:
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:
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:
You can replace the rendered citation with arbitrary text or interpolate it directly:
To cite multiple resources you concatenate them as follows:
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:
You can handle multiple bibliographies by providing a target parameter to citation macros:
You can then render all citations targeting a specific bibliography by using the target parameter again:
bibliography::foo[]
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:
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:
=== Styling
The default style for citations and bibliographies is apa.
You can change that in the header:
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:
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:
=== 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.
==== Sort By Single Key
To sort in a single key - say, the rendered author name - it's as simple as
==== Reverse Sort
However you might want to reverse the order:
==== 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:
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*citealtcitealt*citepcitep*citealpcitealp*citeauthorciteauthor*citeyearciteyearparnociteTo 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:
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.
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.
==== CLI usage
All header attributes described above can also be passed through the commandline as is customary. E.g.:
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.
Setup your environment.
Run the test suite
== 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:
== 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].
FAQs
Unknown package
We found that asciidoctor-bibliography demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.