Zotero

Zotero is a reference manager to keep track of the work of others. We use Zotero as a content helper to generate lists of background reading or additional information on documentation pages.

System overview

This is a works-for-me solution that could eventually be replaced by an Asciidoc macro, an Antora pipeline component, and/or a bibtex-based approach, to be more in line with common practice.

This version does not build a bibliography based on in-text references, it just creates a list as HTML file to be included. There is no way to cross reference or link between the text and a specific reference.

Zotero subsystem overview
Figure 1. Zotero subsystem overview

Activities

The editor performs a few tasks.

Organise references in Zotero

Zotero lets you organise references in collections and label them with tags. Both can be used to later retrieve a set of references from Zotero. We use a collection for each page. [1]

It is possible to move collections around in Zotero without changing their identifier. This decouples the exact hierarchy and organisation of collections in Zotero from the documentation pages.

Collections can be part of a personal library or a group library.

Current organisation of collections in Zotero
Figure 2. Current organisation of collections in Zotero

Add Zotero lookup details to the content

Each content component can have a file called zotero in the same folder as the antora.yml file. This file contains a list of reference lists to generate.

A zotero file with two lists
collections/NAN7TETL/ ROOT background-refs (1)
collections/JBHC442F/ module1 further-reading mytag (2)
1 Get all references in the collection, and add them as background-refs.html to the partials folder of the ROOT module.
2 Get references in the collection with tag mytag, and add them as further-reading.html to the partials folder of the module1 module.

The collection id can be found in the web address when visiting the collection online.

Also, the Zutilo addon offers a way to create links to a collection in either the Zotero application or the Zotero website for your library. This is an alternative option to find the collection id.

Run the content helper

The content helper get-zoteros is a script that can be run in a component folder. See below for the script itself. It will process the zoteros file and use the Zotero API to do two retrievals:

  1. Get an HTML-formatted list of references using a specified CSL file. [2]

  2. Add the same list formatted as COinS, to let readers quickly add the references to their own reference manager. [3]

The resulting HTML file is stored in the partials folder of a module. This partial file is also included in version control, so the helper only needs to be run when references have changed.

Include the reference list in a page

The reference list can be added to a page with a simple Asciidoc include statement in a pass-through block.

Add the references to an Asciidoc page
++++
include::partials$background-refs.html[]
++++

Content helper script

The get-zoteros script
#!/bin/bash
# load a series of zotero collections for an Antora documentation component
ZAPI=https://api.zotero.org
ZSRC=users/12345 (1)
ZKEY="Authorization: Bearer xyzxyz" (2)
CSL=https://www.drostan.org/drostan.csl (3)

if [[ -e antora.yml && -e zotero ]]; then
  cat zotero | while read zget module partial tag; do
    if [[ -n "$tag" ]]; then
      with_tag=" with tag $tag"
      p_tag="&tag=$tag"
    else
      with_tag=
      p_tag=
    fi
    echo "Getting ${zget}items$with_tag and putting into $module/partials/$partial.html"
    mkdir -p "modules/$module/partials"
    curl -sS -H "$ZKEY" "$ZAPI/$ZSRC/${zget}items?format=bib&linkwrap=1$p_tag&itemType=-attachment&style=$CSL" -o "modules/$module/partials/$partial.html"
    echo "Appending COinS info"
    curl -sS -H "$ZKEY" "$ZAPI/$ZSRC/${zget}items?format=coins$p_tag&itemType=-attachment" >> "modules/$module/partials/$partial.html"

    echo "Include references with:" (4)
    echo -e "\n[bibliography]"
    echo -e "== Background references\n"

    echo "++++"
    echo "include::partial\$$partial.html[]"
    echo -e "++++\n"
  done
fi
1 Choose between 'users' and 'groups', and replace 12345 with the appropriate user or group id. The user id can be found on Zotero’s Feeds/API settings page.
2 When using a group library, add an API key to get access.
3 Replace the URL of the CSL file with the desired style definition.
4 Print an Asciidoc snippet for a collection, that can be included in a page.

The Zotero API documentation can help to change the API call to your liking.

Twitter LinkedIn Github Gitlab Meetup RSS Miro Trello Zotero Hypothesis