Bibcite-CSL

• Contributors: https://github.com/ShadyChars/
• Tags: references, CSL, CSL JSON, RIS, citations
• Requires at least: 3.1.0
• Tested up to: 6.4.2
• Stable tag: 2.0.0
• License: GPLv2 or later
• License URI: http://www.gnu.org/licenses/gpl-2.0.html

Bibcite-CSL adds and formats scholarly references in WordPress content. It supports CSL-JSON input files and formats their contents using CSL.

Description

Bibcite-CSL consumes online CSL-JSON files to give you access to scholarly references within your posts and pages. It allows you insert standalone bibliographies via the [bibtex] shortcode, and to insert notes and a corresponding bibliography with the [bibshow]...[/bibshow] and [bibcite] shortcodes.

Source reference data is parsed from CSL-JSON files available at URLs specified via shortcode (e.g. [bibtex file=http://example.com/my-library.json]). Where a shortcode does not specify a library, a default library location can be set.

Individual references are transformed into HTML using a specified Citation Style Language (CSL) style, and are then collected into groups for display using a specified Twig template (e.g. [bibtex style=ieee style=my-ordered-list]). Again, styles and templates can be specified via shortcode or, if omitted, will be replaced by default values.

Acknowledgements

Bibcite is inspired by and shares a number of concepts with Benjamin Piwowarski's Papercite plugin. It is built on Devin Vinson's WordPress Plugin Boilerplate. Thank you both!

Thanks also to the authors and maintainers of the following projects:

• Monolog
• Citation Style Language
• cocur/slugify
• PSR Log
• seboettg/citeproc-php CHANGE
• Twig

Installation

This section describes how to install the plugin and get it working.

Build

Bibcite-CSL is not yet available in a ready-to-install form. To obtain and build a copy:

1. Ensure you have installed PHP 7.0 or above
2. Clone or download this repository
3. Run composer install to retrieve all dependencies. If you do not have Composer already, you may install it either locally or globally as desired.

Deploy

Having obtained and built the plugin:

1. Upload the contents of the local bibcite folder to a new /wp-content/plugins/bibcite directory
2. Activate the plugin through the WordPress 'Plugins' menu
3. Configure default values via 'Settings' → 'Bibcite-CSL'

Usage

Bibcite-CSL allows you to insert standalone bibliographies and/or notes and citation into WordPress posts and pages. Citations are loaded from a specified CSL JSON file before being formatted using either a built-in or custom CSL style file and then assembled into a note or bibliography using a built-in or custom Twig template.

Note that where practicable, shortcode and attribute usage mirror those of Benjamin Piwowarski's Papercite plugin.

Standalone Bibliographies

A standalone bibliography is added by the non-enclosing [bibtex] shortcode. The shortcode's attributes are processed to discover the content and style of the bibliograpy before being rendered into HTML. The shortcode accepts the following attributes:

Attribute	Value	Examples
file	A URL pointing to a CSL JSON library available online. Local files are not supported. If not specified, the default library will be used.	url=http://example.org/my-library.json
key	A comma-separated list of citation keys (or, in CSL terms, "IDs"). If a given key is not present in the associated CSL JSON library, it will be ignored.	key=Smith2018 key=Smith2018,Jones1992
style	The name of a CSL style with which individual citations will be rendered. If not specified, the default [bibtex] style will be used.	style=ieee style=chicago-fullnote-bibliography
template	The name of a Twig template with which rendered citations will be transformed into HTML. If not specified, the default [bibtex] template will be used.	template=bibtex-unordered-list
sort	If present, the name of a CSL schema value by which to sort all bibliography entries.	sort=title sort=author sort=issued
order	If present, selects either ascending or descending sort order. If no sort attribute is present, this has no effect.	order=asc order=desc

Notes and Citations

To create a bibliography from citations made within the text of a post or page, use the enclosing [bibshow]...[/bibshow] along with the non-enclosing [bibcite] shortcodes. The opening and closing [bibshow] shortcodes "capture" all citations made within them using [bibcite] shortcodes, and, having done so, generate and emit the resulting bibliography at the location of the closing [/bibshow] shortcode.

The opening [bibshow] shortcode supports the following attributes:

Attribute	Value	Examples
file	A URL pointing to a CSL JSON library available online. Local files are not supported. If not specified, the default library will be used.	url=http://example.org/my-library.json
style	The name of a CSL style with which individual citations within the generated bibliography will be rendered. If not specified, the default [bibshow] style will be used.	style=ieee style=chicago-fullnote-bibliography
template	The name of a Twig template with which individual rendered citations will be combined into an HTML bibliography. If not specified, the default [bibshow] template will be used.	template=bibshow-definition-list

[bibcite] shortcodes support the following attributes:

Attribute	Value	Examples
key	A comma-separated list of citation keys. If a given key is not present in the associated CSL JSON library, it will be ignored.	key=Smith2018 key=Smith2018,Jones1992
style	The name of a CSL style with which individual citations will be rendered. If not specified, the default [bibcite] style will be used.	style=ieee style=chicago-fullnote-bibliography
template	The name of a Twig template with which individual rendered citations will be transformed into an HTML note. If not specified, the default [bibcite] template will be used.	template=bibcite-numbered-note

Here's an example of how [bibshow]...[/bibshow] and [bibcite] shortcode work together to create notes and an accompanying bibliography:

[bibshow]
This is a note referring to a single source.[bibcite key=Reference1] And this is another.[bibcite key=Reference3]

This is a note referring to two sources.[bibcite key=Reference1,Reference2]
[/bibshow]

This generates three notes in the text itself:

• The first refers to Reference1
• The second refers to Reference3
• The third refers to Reference1 and Reference2

The closing [/bibshow] shortcode is replaced by a bibliography that contains the set of all such references in the order in which they were encountered:

1. Reference1
2. Reference3
3. Reference2

Note that Reference1 appears only once in the generated bibliography.

The exact appearance of the generated notes and citations is dependent on the selected CSL styles and Twig templates for the [bibcite] and [bibshow] shortcodes. See the next section for details.

Styles, Templates and the Rendering Process

All three support shortcodes apply the same rendering process:

1. Find the set of referenced citations
2. Render each citation individually using a specified CSL style (taken from the shortcode's style attribute or inherited from the default value in the settings)
3. Combine the individual rendered citations into a single chunk of HTML using a specified Twig template (taken from the shortcode's template attribute or inherited from the default value in the settings)

In the case of [bibtex] and [bibshow] shortcodes, the set of referenced citations are those to be displayed as part of the generated bibliography. In the case of [bibcite] shortcodes, the set of references citations are those referred to by the shortcode's key attribute.

In all cases, all relevant rendered citations are presented to the Twig template engine as an array (called $entries) of associative arrays with well-defined structures. As an example:

$entries = array(
    array(
        "index" => 1,           // 1-based numeric index
        "key" => "Reference1",  // Citation key
        "csl" => "...",         // CSL entry as JSON string
        "entry" => "..."        // Rendered citation
    ),
    array(
        "index" => 2,
        "key" => "Reference2",
        ...
    ),
    ...
);

A simple Twig template to render $entries as a bibliography might look like this:

<dl>
{% for entry in entries %}
    <dt>{{ entry.index + 1 }}.</dt>
    <dd>{{ entry.entry | raw }}</dd>
{% endfor %}
</dl>

Custom styles and templates

Bibcite-CSL has a large number of built-in CSL styles, all taken from the official repository of CSL styles. These are available via autocomplete from the 'Settings' page. Additionally, Bibcite-CSL comes with a limited set of Twig templates:

• bibtex-unordered-list is intended to render [bibtex] bibliographies as simple unordered lists
• bibcite-numbered-note and bibshow-definition-list are intended to be used together to present [bibtex] and [bibshow] shortcodes as numbered notes pointing to a numbered bibliography

Again, these are available via autocomplete from the 'Settings' page.

However, it is possible to add both user-defined CSL styles and Twig templates. Styles (with the extension .csl) should be placed in the styles directory and templates (with the extension .twig) should be placed in the templates directory; having done so, custom styles can now be set as defaults in the 'Settings' page or used via style or template shortcode attributes as required.

Known Issues

• Only remote libraries are supported
• Only CSL JSON libraries are supported
• The "cache cleared" admin message erroneously reappears after settings are saved
• There are no unit tests

Changelog

1.0.0

First version.

1.1.3

• Improvements to Wordpress path handling.
• Added UTs for basic cases.

2.0.0

• Dropped Bibtex support for libraries in favour of CSL-JSON
• Updated all dependencies