citeproc-plus

citeproc-plus incorporates 2000+ styles and 50+ locale files from the Citation Style Language project, as well as citeproc-js, the JavaScript CSL processor library by Frank Bennett.

This is an early version so be aware that the API may change. You can try a demo at https://fiduswriter.github.io/citeproc-plus/.

This package is meant for those who want to use citeproc-js, but don't want to have to deal with retrieving and storing citation styles and localizations from other places on the web.

How to use

1. Install it from npm together with your other dependencies:

   npm install citeproc-plus --save

2. Configure your bundler to emit the .json.gz style and locale chunks as static assets (most modern bundlers, including Vite, Webpack, and Rollup, do this automatically for non-JavaScript imports). With Webpack's asset/resource module type, for example:

module.exports = {
  mode: "production",
  output: {
    publicPath: "dist/",
  },
  module: {
    rules: [
      {
        test: /\.json\.gz$/i,
        type: 'asset/resource',
      },
    ],
  },
};

3. Import CSL and styles in your app:

import {CSL} from "citeproc-plus"

4. Where in citeproc-js you would have called:

const citeproc = new CSL.Engine(sys, style, lang, forceLang)

Do instead:

const csl = new CSL()

const citeproc = await csl.getEngine(
  sys, // required, same as for citeproc-js, but without the retrieveLocale method
  styleId, // required, The id of the style to use
  lang, // optional, same as for citeproc-js
  forceLang // optional, same as for citeproc-js
)

to create a selector of all available styles:

csl.getStyles().then(
  styles => dom.innerHTML =
    `<select>${
      Object.entries(styles).map(
        ([key, value]) => `<option value="${key}">${value}</option>`
      ).join('')
    }</select>`
)

or if you prefer the then()-function, do:

const csl = new CSL()

let citeproc

csl.getEngine(
  sys, // required, same as for citeproc-js, but without the retrieveLocale method
  styleId, // required, The id of the style to use
  lang, // optional, same as for citeproc-js
  forceLang // optional, same as for citeproc-js
).then(
  engine => citeproc = engine
)

Notice that you only need one CSL instance with which you can create any number of citeproc instances with different styles, languages and sys objects connected to them. Notice also that the method to get an engine is asynchronous as it potentially has to download files from your static files storage.

Advanced uses

JATS

There is an extra style with the styleId jats that can be used as part of conversion packages. This style is not listed among the list of styles as it is not meant for human consumption.

Manipulating a style in JavaScript

If instead of the styleId you hand it a preprocessed style object it will use it as well without caching.

Registering your own styles

If you want to use a style that is not bundled with citeproc-plus (for example one loaded from disk or fetched from your own server), register the preprocessed style object under an id and then reference it by that id:

const csl = new CSL()
csl.registerStyle("my-style", preprocessedStyleObject)

const citeproc = await csl.getEngine(sys, "my-style", lang)

As a convenience, createCSL builds a CSL instance with a map of styles already registered:

import {createCSL} from "citeproc-plus"

const csl = createCSL({"my-style": preprocessedStyleObject})
const citeproc = await csl.getEngine(sys, "my-style", lang)

Registered styles take precedence over the bundled catalog, and their locales are resolved natively in both the browser and Node.js.

Importing CSL

Notice that the styles in this package are not stored in the citation style language (CSL) directly. There is a tool to convert CSL to the JSON of preprocessed style object that is needed here.