Neutral Political Machine

    @zettlr/citr
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.2 • Public • Published

    Citr

    Citr

    Converts Markdown Citations to CSL JSON

    A small library for parsing Markdown citeproc citations to valid CSL JSON (and vice versa).

    Description

    This module transforms citations as they are described in the Pandoc manual into valid CSL JSON that can then -- for instance -- be passed to citeproc-js.

    Install

    With NPM:

    $ npm install @zettlr/citr

    With Yarn:

    $ yarn add @zettlr/citr

    Usage

    Citr.parseSingle(markdown, strict?) // Parses a single citation from Markdown to CSL JSON
    Citr.makeCitation(csl) // Converts a CSL JSON citation to Markdown
    Citr.util.extractCitations(text, strict?) // Extracts all citations from a text
    Citr.util.validateCitationID(key, strict?) // Validates a given citation key

    Citr exposes a small API that you can conveniently use:

    const Citr = require('Citr')
    
    let myCitation = '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
    
    let csl = Citr.parseSingle(myCitation)
    
    /*
    [
      {
        prefix: 'see',
        suffix: '',
        id: 'doe99',
        locator: '33-35',
        label: 'page',
        'suppress-author': true
      },
      {
        prefix: 'also',
        suffix: '',
        id: 'smith04',
        locator: '1',
        label: 'chapter',
        'suppress-author': false
      }
    ]
    */

    If the citation contains any malformed partial citations, Citr will throw an error, so to test for errors, use try/catch constructs:

    const Citr = require('Citr')
    let myCitation = '[Malformed ID inside @.this key]'
    let csl = ''
    
    try {
      csl = Citr.parseSingle(myCitation)
    } catch (err) {
      console.error(`The citation was malformed.`)
    }

    To extract all citations that are inside a given Markdown file/text, Citr exposes a convenient function:

    const Citr = require('Citr')
    
    let myText = 'This is some Text, where both Doe [-@doe99] and others said something [see -@doe99, pp. 33-35; also @smith04, chap. 1]. Of course, this is debatable.'
    
    let citations = Citr.util.extractCitations(myText)
    /*
    [
      '[-doe99]',
      '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
    ]
    */

    You can then afterwards pass all citations in a for-loop through the parseSingle-function.

    If you simply want to conveniently check an ID, use the utility function validateCitationID:

    const Citr = require('Citr')
    
    let goodKey = '@Doe1990'
    let badKey = '@.wrongKey'
    
    Citr.util.validateCitationID(goodKey) // true
    Citr.util.validateCitationID(badKey) // false

    Last but not least you may want to generate a Markdown citation string from a given CSL JSON object. To do so, simply pass a CSL JSON object to the makeCitation function. The only required attribute is id. Please note that this conversion is not language-sensitive, but will output everything as English text. Thereby it can be passed again to the parseSingle-function to retrieve the correct citation.

    const Citr = require('Citr')
    
    const csl = [
      {
        prefix: 'see',
        suffix: '',
        id: 'doe99',
        locator: '33-35',
        label: 'page',
        'suppress-author': true
      },
      {
        prefix: 'also',
        suffix: '',
        id: 'smith04',
        locator: '1',
        label: 'chapter',
        'suppress-author': false
      }
    ]
    
    let markdownCitation = Citr.makeCitation(csl)
    /*
    '[see -@doe99, pp. 33-35; also @smith04, chap. 1]'
    */

    You can, of course, also pass one single object to the engine.

    Legacy ("strict") mode

    The strict parameter is optional and restores the behavior of versions pre 1.1.0 in that functions validating citekeys can either apply a strict mode or a "loose" mode. In strict mode, only a very small subset of ASCII characters are allowed for citekeys (no umlauts as ö, ü, é, è, non-latin script, etc.), while the loose mode will allow as many letter characters as possible. By default, strict mode is off (strict = false). To enable strict mode, pass true to any of the functions that allow the strict mode.

    Example:

    const Citr = require('Citr')
    
    let asciiKey = '@Doe1990'
    let unicodeKey = '@村上2018'
    
    Citr.util.validateCitationID(asciiKey) // true
    Citr.util.validateCitationID(asciiKey, true) // true (strict mode enabled)
    Citr.util.validateCitationID(unicodeKey) // true (Japanese characters are allowed)
    Citr.util.validateCitationID(unicodeKey, true) // false (only ASCII characters allowed)
    
    try {
      let citation = Citr.parseSingle(unicodeKey, true) // Enable strict mode
    } catch (err) {
      console.error('An error will be thrown, as parseSingle will call validateCitationID using strict mode')
    }

    Contributions

    Contributions and PRs are welcome. By contributing, you agree that your code will also be made available under the GNU GPL v3 license.

    License

    This software is licenced via the GNU GPL v3-License.

    The brand (including name, icons and everything Citr can be identified with) is exluded and all rights reserved. If you want to fork Citr to develop another library, feel free but please change name and icons.

    Install

    npm i @zettlr/citr

    DownloadsWeekly Downloads

    50

    Version

    1.2.2

    License

    GPL-3.0

    Unpacked Size

    106 kB

    Total Files

    46

    Last publish

    Collaborators

    • nathanlesage