citeproc-js Documentation

citeproc-js is a JavaScript implementation of the Citation Style Language (CSL), an open XML-based standard for describing bibliographic citation styles. It allows for modular control over how citations and bibliographies are formatted, enabling users to switch styles (e.g., from sciences to humanities or law) without changing the underlying document data.

Key capabilities include:

• Disambiguation: Handles author-date disambiguation (e.g., following Chicago Manual of Style).
• Sorting: Supports complex sorting rules with multiple keys and arbitrary orders (e.g., AGU journal styles).
• Parallel Citations: Supports legal citation requirements, such as citing a case in multiple reporters.
• On-the-fly Updates: The API supports targeted, context-sensitive updates to citations when document content is inserted, deleted, or edited.
• Localization: Supports localized date formatting and style-supplied labels.
• Name Handling: Sophisticated handling of European name particles (e.g., "von", "van", "di") for sorting and rendering.
• In-field Formatting: Recognizes a subset of HTML for scientific markup (superscript, subscript, italics, etc.) and transforms it into the target output format (HTML, RTF, LaTeX, etc.).
• Multi-lingual Support: Experimental support for transliteration, title translation, and alternative sort strings for Asian languages.

Dates should be provided as JavaScript objects containing a date-parts array. Each inner array represents a date (start or end) in the order: [year, month, day].

• Types: Elements can be numeric strings or numbers.
• Seasons: A season element can be included. Values 1 through 4 map to Spring, Summer, Fall, and Winter. Other strings are treated as literals.
• Circa: For approximate dates, include a circa element with a non-nil value.
• Ranges: To specify a date range, provide two arrays within date-parts. For an open-ended range, use [0, 0] for the end elements.
• Literals: Use a literal element to pass a raw string (e.g., "13th century").

// Standard date
{ "issued" : { "date-parts" : [ [ "2000", "1", "15" ] ] } }

// Date range (Nov 2000 to Dec 2000)
{ "issued" : { "date-parts" : [ [ 2000, 11 ], [ 2000, 12 ] ] } }

// Open-ended range
{ "issued" : { "date-parts" : [ [ 2008, 11 ], [ 0, 0 ] ] } }

// Approximate date
{ "issued" : { "date-parts" : [ [ -225 ] ], "circa" : 1 } }

// Literal string
{ "issued" : { "literal" : "13th century" } }

To support styles that require splitting citation content (e.g., placing the author name in the text and the numeric identifier in a superscript), you can use two control elements in sequence:

1. author-only: When passed to makeCitationCluster(), it returns the author name without decorative markup (like italics or superscript). In numeric styles, it may provide a localized label and the numeric identifier.
2. suppress-author: When passed to processCitationCluster() or appendCitationCluster(), it suppresses the rendering of names. In numeric styles, it suppresses output if the identifier was already provided in the first step.

Workflow for split citations (e.g., Author-Date or GB7714-87):

1. Call makeCitationCluster() with {"author-only": 1} to get the author part.
2. Call processCitationCluster() with {"suppress-author": 1} to get the remaining citation part.

// 1. Get the author part
var my_ids = {
     ["ID-3", {"author-only": 1}]
};
var result = citeproc.makeCitationCluster( my_ids );

// ... later ...

// 2. Get the rest of the citation (suppressing the author)
var citation, result;

citation = {
     "citationItems": ["ID-3", {"suppress-author": 1}],
     "properties": { "noteIndex": 5 }
};
[data, result] = citeproc.processCitationCluster( citation );

The <legal/> CSL element is used to trigger the loading of jurisdiction-specific style modules. When the processor encounters this element, it invokes citeproc.sys.loadJurisdictionStyle() and hands over control of the item's processing to the matched legal style module.

Usage Requirements

• Placement: The <legal/> element should be placed at the beginning of processing, typically under the <citation/> or <bibliography/> sections.
• Required Attribute:
  • default (<string>): Specifies the default jurisdiction to use if no matching style is found for the item's jurisdiction.
• Sub-elements: The element requires specific sub-elements as defined in the CSL schema (refer to the implementation for specific required sub-elements).

<!-- Example conceptual structure -->
<citation>
  <legal default="US">
    <!-- subelements -->
  </legal>
  <!-- remaining citation processing -->
</citation>

A CSL JSON object consists of three types of fields: ordinary fields, creator fields, and date fields. Each type has specific requirements for how data is structured to ensure correct citation rendering.

Field Types Overview

1. Required Metadata Fields:

   • id: Required. A unique string or numeric value used to identify the item.
   • type: Required. A valid CSL or CSL-M type (e.g., book).

2. Ordinary Fields (e.g., title):

   • Can be set as simple strings or numbers.

3. Creator Fields (e.g., author):

   • Must be an array of objects. Supports personal names (using family and given), discrete name components, and institutional names (using literal).

4. Date Fields (e.g., issued):

   • Can be set using structured date-parts (arrays) or a raw string format.

{
   "id": "item123456789",
   "type": "book",
   "title": "Book One",
   "author": [
      {
         "family": "Jones",
         "given": "Michael"
      }
   ],
   "issued": {
      "date-parts": [[ 2000, 3, 15 ]]
   }
}

When providing author data, you can handle complex name structures using specific elements:

• Particles: Use dropping-particle (e.g., "von") and non-dropping-particle (e.g., "van") to separate particles from the family and given names.
• Suffixes: Use the suffix element for name suffixes like "Jr." or "III".
• Comma Suffixes: If a suffix is preceded by a comma in the output, include the comma-suffix: "true" field.
• Non-Latin/Cyrillic Scripts: The processor automatically handles non-Byzantine scripts (e.g., Kanji) by displaying the family name first.
• Static Ordering: To force a Latin or Cyrillic transliteration to behave like a non-Byzantine name (fixed family-name-first ordering), include a static-ordering element in the name array with any truthy value.

{ "author" : [
       { "family" : "Humboldt",
         "given" : "Alexander",
         "dropping-particle" : "von"
       },
       { "family" : "Gogh",
         "given" : "Vincent",
         "non-dropping-particle" : "van"
       },
       { "family" : "Bennett",
         "given" : "Frank G.",
         "suffix" : "Jr.",
         "comma-suffix": "true"
       },
       { "family" : "Murakami",
         "given" : "Haruki",
         "static-ordering" : 1
       }
     ]
   }