citeproc-js-server is a Node-based server that generates citations and bibliographies using citeproc.js.
For optimal performance, you should maintain separate directories with JSON styles/locales. This can be done by running the included xmltojson.py:
./xmltojson.py ./csl ./csljson
./xmltojson.py ./csl-locales ./csljson-locales
Or only those updated within the last 5 minutes:
xmltojson.py --changed 300 ./csl ./csljson
xmltojson.py --changed 300 ./csl-locales ./csljson-locales
And point cslPath
and localesPath
in config/local.json to point to the json directories.
Also note that the citation server automatically watches the style and locale directories to automatically use the new versions when they're pulled. This is subject to platform caveats
Get citeproc-js-server
git clone --recurse-submodules https://github.com/zotero/citeproc-js-server.git
cd citeproc-js-server
npm install
Start the server:
npm start
If all is well, you will see:
info Server running at http://127.0.0.1:8085
Now to test the server using the sampledata.json file provided in the citeproc-js-server sources. Try posting it to your server, from a separate console:
curl --header "Content-type: application/json" \
--data @sampledata.json -X POST \
'http://127.0.0.1:8085?responseformat=html&style=modern-language-association'
You should see a response similar to this:
<div class="csl-bib-body">
<div class="csl-entry">Abbott, Derek A. et al. “Metabolic Engineering of <i>Saccharomyces
Cerevisiae</i> for Production of Carboxylic Acids: Current Status and Challenges.” <i>FEMS
Yeast Research</i> 9.8 (2009): 1123–1136. Print.</div>
<div class="csl-entry"><i>Beck V. Beck</i>. Vol. 1999. 1999. Print.</div>
<div class="csl-entry">---. Vol. 733. 1999. Print.</div>
...
</div>
citeproc-js-server uses node-config for configuration. Configuration parameters can be specified in config/local.json or other files and formats supported by node-config.
citeproc-js-server now supports CSL styles that has been converted to JSON. This improves performance significantly on style initialization, and somewhat on style execution over the JSDOM XML parsing mode. Local styles can be converted ahead of time, which improves performance even futher. Otherwise both local and remote styles will be converted at run time.
There is a Python script, xmltojson.py, to convert a single file or a directory, including
the option to only convert files that have been modified within a specified time limit, to better handle periodic pulling of style/locale changes.
To use pre-converted json styles, just point the cslPath
preference at the directory of converted styles.
Start citation server
npm start
Run a test with all independent styles in the csl directory:
node ./test/testallstyles.js
The service responds to HTTP OPTIONS
or POST
requests only.
When sending a request, various options should be set in the query string of the URL, and the CSL-JSON data should be sent in the content body.
The following query string parameters are recognized:
- responseformat - One of
html
,json
, orrtf
(value is passed through to citeproc.js). Default isjson
. - bibliography - Default is
1
. - style - This is a URL or a name of a CSL style. Default is
chicago-author-date
. - locale - Default is
en-US
- citations - Default is
0
. - outputformat - Default is
html
. - memoryUsage - If this is
1
, and the server has debug enabled, the server will respond with a report of memory usage (and nothing else). Default is0
. - linkwrap - Default is
0
- clearCache - If this
1
, then the server will clear any cached style engines, and reread the CSL styles. This can only be sent from the localhost. Default is0
.
The POST data JSON object can have these members:
- items - either an array or a hash of items
- itemIDs - an array of identifiers of those items to convert. If this is not given, the default is to convert all of the items.
- citationClusters
- styleXML - a CSL style to use
CSL citation styles, included as a Git submodule
CSL locales, included as a Git submodule
The citeproc-js citation processor
We're using npmlog, which has these levels defined:
- silly -Infinity
- verbose 1000
- info 2000
- http 3000
- warn 4000
- error 5000
- silent Infinity
The level at which the server runs is specified in the config file, as the
logLevel
parameter.
In the code, to create a log message at a particular level, for example,
log.warn("Uh-oh!");