rehype-citation
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    rehype-citation

    rehype citation example

    rehype plugin to nicely format citations in markdown documents and insert bibliography in html format. It is meant to be used as a server side plugin and neatly integrates citeproc-js and citation-js within the remark-rehype ecosystem.

    It supports both normal citations (such as [@foo]) and in-text citation (such as @foo), as well as author-date, numerical, and note styles.

    API and options follows very closely to Rmarkdown and Pandoc

    Installation

    This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

    npm install rehype-citation

    Usage

    If you are using the plugin in a node environment, import from rehype-citation/node. For browser environments, import from rehype-citation/browser.

    The following files are exported:

    generator, generator function. Can be used to generate a rehype citation plugin. Takes in a citation-js Cite class. cite, a citation-js Cite instance. Add your own CSL / locales before passing in to the plugin generator . rehype-citation, re-exports the above 2 packages with a pre-configured rehype-citation plugin ready to use. Importing from rehype-citation directs to this file.

    Use this package as a rehype plugin.

    Some examples of how you might do that:

    import rehype from 'rehype'
    import rehypeCitation from 'rehype-citation'
    
    rehype().use(rehypeCitation).process(/* some html */)

    Sample markdown to HTML output

    Input:

    My markdown text [@Nash1950]

    HTML Output:

    <div>My markdown text (Nash, 1950)</div>
    <div id="refs" class="references csl-bib-body">
      <div class="csl-entry">
        Nash, J. (1950). Equilibrium points in n-person games.
        <i>Proceedings of the National Academy of Sciences</i>, <i>36</i>(1), 48–49.
      </div>
    </div>

    Generating your own remark citation plugins

    The default plugin comes configured with the en-US locale and the following CSL styles: apa, vancouver, harvard1, chicago and mla.

    Use the generator function to customize your own remark-citation plugin and add your own CSL styles or locales.

    import Cite from 'rehype-citation/cite'
    import rehypeCitationGenerator from 'rehype-citation/generator'
    import myStyle from '../style'
    import myLocale from '../locale'
    
    const config = Cite.plugins.config.get('@csl')
    config.templates.add('mystyle', myStyle)
    config.locales.add('myLocale', myLocale)
    
    const rehypeCitation = rehypeCitationGenerator(Cite)

    API

    rehype().use(rehypeCitation, [options])

    If no bibliography file is passed, the plugin will be skipped.

    options

    options.bibliography

    Type: string.

    By default, if no bibliography file is passed, the plugin will be skipped.

    Name of bibtex or CSL-JSON file.

    options.path

    Type: string. Default: process.cwd().

    Required, path to file. Will be joined with options.bibliography and options.csl, if provided.

    options.csl

    Type: 'apa'|'vancouver'|'harvard1'|'chicago'|'mla'|string. Default: apa.

    For the main rehypeCitation plugin, one of 'apa', 'vancouver', 'harvard1', 'chicago', 'mla'. A local file path or URL to a valid CSL file is also accepted.

    options.lang

    Type: string. Default: en-US.

    Locale to use in formatting citations. Defaults to en-US. A local file path or URL to a valid locale file is also accepted.

    options.suppressBibliography

    Type: boolean. Default: false.

    Suppress bibliography? By default, biliography is inserted after the entire markdown file. If the file contains [^ref], the biliography will be inserted there instead.

    options.noCite

    Type: string[].

    Citation IDs (@item1) to include in the bibliography even if they are not cited in the document.

    options.inlineClass

    Type: string[].

    Array of classes for inline citations.

    options.inlineBibClass

    Type: string[].

    Array of classes for inline bibliography. Leave empty to disable inline bibliography.

    Limitations

    1. link-citations is not implemented.
    2. In-text citation does not parse additional locator information e.g. @foo [p. 33], please use either [@foo, p. 33] or @foo.
    3. Parsing of locators such as page or chapter is done by heuristics and limited to only en content.
    4. Does not support using curly braces to protect citation key or locator information.

    Install

    npm i rehype-citation

    DownloadsWeekly Downloads

    1,844

    Version

    0.4.0

    License

    MIT

    Unpacked Size

    5.6 MB

    Total Files

    187

    Last publish

    Collaborators

    • timlrx