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. |
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.
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.
zotero
file with two listscollections/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:
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.
Content helper script
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.