• 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: https://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.

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=https://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.

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

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

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.

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'

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.

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:

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:

[bibcite] shortcodes support the following attributes:

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.

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>

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.

• 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

First version.

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

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