Package Exports

@citation-js/plugin-csl
@citation-js/plugin-csl/lib-mjs/index.js
@citation-js/plugin-csl/lib/engines
@citation-js/plugin-csl/lib/engines.js
@citation-js/plugin-csl/lib/index.js
@citation-js/plugin-csl/package.json

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@citation-js/plugin-csl) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@citation-js/plugin-csl

Plugin for CSL output for Citation.js. Output generation is done with citeproc-js.

Install

npm install @citation-js/plugin-csl

Usage

require('@citation-js/plugin-csl')

Formats

Formats and other features added by this plugin. General output options:

template: the style template to use. Currently, the following are built-in:
- apa (default)
- vancouver
- harvard1
lang: the locale to use. Currently, the following are built-in:
- en-US (default)
- es-ES
- de-DE
- fr-FR
- nl-NL
format: output (markup) format. Note: this doesn't support the output format dictionaries
entry (String, Array[String]): entry ID or list of entry IDs to identify the items to cite

Bibliography

This plugin adds the output format bibliography, and accepts the following specific options:

prepend (String, Function): prepend static or dynamic text to each entry
append (String, Function): append static or dynamic text to each entry
nosort (Boolean, default: false): do not sort according to the style-defined rules
asEntryArray (Boolean, default: false): return an array of entries consisting of an id and the output for that individual entry

Here's an example for prepend and append:

let cite = new Cite({ id: 'a', title: 'Item A' })

cite.format('bibliography', { append: ' [foobar]' })
// 'Item A. (n.d.). [foobar]\n'

cite.format('bibliography', { prepend (entry) { return `${entry.id}: ` } })
// 'a: Item A. (n.d.).\n'

And here's another example, possibly more realistic:

let cite = new Cite('Q30000000')

let date = (new Date()).toLocaleDateString()

cite.format('bibliography', {
  format: 'html',
  template: 'apa',
  prepend (entry) {
    return `[${entry.id}]: `
  },
  append: ` [Retrieved on ${date}]`
})

// `<div class="csl-bib-body">
//   <div data-csl-entry-id="Q30000000" class="csl-entry">
//     [Q30000000]: Miccadei, S., De Leo, R., Zammarchi, E., Natali, P. G., &#38; Civitareale, D. (2002). The Synergistic Activity of Thyroid Transcription Factor 1 and Pax 8 Relies on the Promoter/Enhancer Interplay. <i>Molecular Endocrinology</i>, <i>16</i>(4), 837–846. https://doi.org/10.1210/MEND.16.4.0808 [Retrieved on 2018-7-10]
//   </div>
// </div>`

This prepends [$ID]: to each entry, where $ID is the ID of that entry, and appends [Retrieved on $DATE], where $DATE is today (constant for all entries).

Here's an example for asEntryArray:

const cite = new Cite([
  { id: 'a', title: 'Item A', issued: { literal: 2021 } },
  { id: 'b', title: 'Item B', issued: { literal: 2021 } }
])

cite.format('bibliography', { asEntryArray: true })
// [
//   [
//     "a"
//     "Item A. (2021).\n"
//   ],
//   [
//     "b"
//     "Item B. (2021).\n"
//   ]
// ]

Citation

Here's an example for entry:

let cite = new Cite([
  { id: 'a', title: 'Item A', issued: { 'date-parts': [[2016]] } },
  { id: 'b', title: 'Item B', issued: { 'date-parts': [[2017]] } },
  { id: 'c', title: 'Item C', issued: { 'date-parts': [[2018]] } }
])

cite.format('citation')
// '(“Item A,” 2016; “Item B,” 2017; “Item C,” 2018)'

cite.format('citation', { entry: ['a', 'b'] })
// '(“Item A,” 2016; “Item B,” 2017)'

cite.format('citation', { entry: 'a' })
// '(“Item A,” 2016)'

Configuration

It is possible to add different styles and locales.

const { Cite, plugins } = require('@citation-js/core')

Templates

Different CSL Templates can be registered like this:

let templateName = 'custom'
let template = '<?xml version="1.0" encoding="utf-8"?><style ...>...</style>' // The actual XML file

let config = plugins.config.get('@csl')
config.templates.add(templateName, template)

let example = new Cite(...)
example.format('bibliography', {
  format: 'html',
  template: templateName,
  lang: 'en-US'
})

Locales

Different CSL Locales can be registered like this:

let language = 'en-GB'
let locale = '<?xml version="1.0" encoding="utf-8"?><locale ...>...</locale>' // The actual XML file

let config = plugins.config.get('@csl')
config.locales.add(language, locale)

let example = new Cite(...)
example.format('bibliography', {
  format: 'html',
  template: 'apa',
  lang: language
})

Engine

The configuration object also exposes an internal method to prepare a Citeproc engine with given data and configuration:

let config = plugins.config.get('@csl')

let citeproc = plugins.engine(
  /* data: */ [{ ... }],
  /* template: */ 'apa',
  /* locale: */ 'en-US',
  /* format: */ 'html'
)

let sortedIds = citeproc.updateItems(/* ids: */ [...])
let makeBibliography = citeproc.makeBibliography()