asciidoctor-csl: CSL integration for AsciiDoc

asciidoctor-csl adds CSL integration for AsciiDoc. The macros to use are heavily inspired by asciidoctor-bibtex. It is thus not possible to use both at the same time.

Note: this gem is new and subject to change.

Use

Loading the extension:

asciidoctor -r asciidoctor-csl document.adoc

You need to configure which bibliography file to use, in CSL-JSON (.json), or as YAML (.yml or .yaml):

= My document
:csl-file: references.json
:csl-style: apa

As shown by cite:smith2020[], ...

== References

bibliography::[]

Configuration

These document attributes configure the extension:

csl-file: The bibliography file, relative to the document. Required: without it, the macros are not rendered.
csl-style: The citation style, as the name of a style from the CSL style repository, e.g. apa, ieee, or chicago-notes-bibliography-17th-edition. Defaults to ieee.
csl-lang: The language used for terms such as "p." or "and". Defaults to the lang attribute of the document, or en if that is not set.
csl-link-title: If set, the title of each entry links to the source’s DOI or URL. Citations are not affected. Override it per macro with the link-title attribute of bibliography::[] and bibitem:key[].

Citations

cite:key[] cites a source. Cite multiple sources in one citation with commas: cite:smith2020,doe2019[].

The macro accepts these options:

Attribute	Description
locator (1st positional)	The location in the source, e.g. `cite:smith2020[12]`. Quote values containing a comma: `cite:smith2020["12, 14"]`.
label (2nd positional)	The kind of locator, e.g. `cite:smith2020[3, chapter]`. Defaults to `page`. Other values are `book`, `column`, `figure`, `folio`, `issue`, `line`, `note`, `opus`, `paragraph`, `part`, `section`, `sub-verbo`, `verse` and `volume` (supports all options from citeproc).
`prefix`	Text placed before the citation, e.g. `cite:smith2020[prefix=see]`.
`suffix`	Text placed after the citation, e.g. `cite:smith2020[suffix=for details]`.
`link`	If the document has a bibliography, each cited item links to its entry. Use `link=false` to disable this for a single citation.
`parens`	Use `parens=false` to leave out the parentheses around the citation, e.g. to write "(see Smith, 2020, or the appendix)" yourself. This removes the prefix and suffix the style puts around the whole citation; it does not affect brackets around each item, as in IEEE.

With multiple keys, the locator and suffix apply to the last source, and the prefix to the first. Footnotes are supported as well. Citations in section titles are not supported.

Bibliography

bibliography::[] renders the bibliography. By default, it only renders the cited sources. Use bibliography::[select=all] to include everything in the bibliography.

Use bibliography::[link-title=true] or bibliography::[link-title=false] to override the csl-link-title setting for this bibliography.

Each entry gets an anchor with the source’s key as ID, like [smith2020].

Single entries

bibitem:key[] renders the entry of a single source inline. It does not count as a citation: the source is not added to the bibliography and does not affect the numbering. Like the bibliography, it accepts link-title=true or link-title=false to override the csl-link-title setting.

Citation Style Language support

The gem supports almost everything that its CSL processor (citeproc) supports. A few tweaks are done to make it work better with AsciiDoc:

The gem renders quotes as "curly" quotes, so AsciiDoctor will render them. Use a good output template, like asciidoctor-html5s
The source of the CSL bibliography is parsed as AsciiDoc. This means:
- You can add formatting inside your bibliography using AsciiDoc
- The gem does not support `citeproc-js’s default for inline HTML. A straight export from Zotero probably won’t work with all AsciiDoc’s output formats (but should work when outputting HTML).

How does it work?

This gem works by using citeproc-ruby and csl-styles to render the items. It includes a citeproc plugin to render to AsciiDoc natively. Otherwise, it is mostly a thin layer between AsciiDoctor and those gems.

License

This gem is published under the EUPL 1.2. See the LICENSE.txt file.

asciidoctor-csl

Runtime