timlrx / rehype-citation

Rehype plugin to add citation and bibliography from bibtex files

Rehype-Citation

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. Parsing of citations and all the wonderful regexes are adapted from Zettlr.

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

Note styles is only compatible with Github Formatted Markdown (GFM). It is recommended to run remark-gfm before rehype-citation to ensure all footnote elements are correctly formatted.

API and options follows very closely to Rmarkdown and Pandoc

Examples

• Citations with Bibliography
• Suppress Bibliography
• Custom CSL
• Footnote style
• Link Citations

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|string[].

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

Name or path to Bibtex, CSL-JSON or CFF file. If multiple files are provided, they will be merged.

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.

options.linkCitations

Type: boolean. Default: false.

If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numeric styles only).

rehype-citation's Issues

`options.CSL` does not support local file

Hi again, I found that setting options.CSL to be the path to a local CSL style file did not have any effect.

A quick digging found that options.CSL is read directly into Cite.plugins.config.get('@csl').engine without file reading and template addition.

I see that you wrote that we need to add locales or styles using the generator function. However, I did try executing config.templates.add('nature', await readFile('https://www.zotero.org/styles/nature'))
between these two lines

rehype-citation/src/generator.js

Lines 138 to 139 in 81362c8

	const config = Cite.plugins.config.get('@csl')
	const citeproc = config.engine(citations.data, citeFormat, options.lang || 'en-US', 'html')

and it seems to work just fine.

Is there a reason why we need to run a generator function beforehand? At least we need to prevent it from failing silently.

Links and backlinks to the references list

For the markdown input:

My markdown text [@Nash1950]

can we have links to the references list and backlinks to the text, and an unordered list as:

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

Thank you for the great plugin!

Refactor cite.js

Currently cite.js is based on citation-js but converted to ESM. There are 3 issues:

1. The build works fine in a standalone test but there seems to be some issue integrating with the vite e2e test. Should try removing the side effects and examining the possible issue.

2. Because @citation-js is cjs, it also hard to use the lib-mjs functions directly since references to other @citation-js plugin is assumed to be cjs...

3. The default cite.js plugin also adds quite a few possibly redundant locales and styles. Using a custom entry point could help further reduce bundle size.

Currently, the rehype plugin mainly uses the conversion function provided by @citation-js plugins. Maybe bypassing Cite completely might be another solution.

en-GB language option no longer works for v0.4.0

The en-GB language option no longer seems to work since upgrading to v0.4.0

Question: Better support for semantic HTML

Not sure how doable this is, but it would be nice to have better support for semantic HTML using the cite tag around titles, and to provide something like <span lang=""> if the bibliography delivers a proper language for the entry.

Cannot find references if they're inside a table

Hi there, I'm using the plugin with docusaurus.

I have a table, and if I put the citation ([@example]) inside a table, the plugin won't be able to find it.

Example:

Key Scheme	Description
sr25519	Schnorr signature on Ristretto compressed ed25519 points as implemented in TODO
ed25519	The ed25519 signature complies with [@josefsson_edwards-curve_2017] except for the verification process which adhere to Ed25519 Zebra variant specified in [@devalence_ed25519zebra_2020]. In short, the signature point is not assumed to be on in the prime ordered subgroup group. As such, the verifier must explicitly clear the cofactor during the course of verifying the signature equation.
secp256k1	Only for outgoing transfer transactions.

Add anchor links to references

Hello,

I really like your package, thank you for your work!

It would be really cool if references could be clickable anchor links to the corresponding bibliography entry. This would mimic the behavior with latex-generated PDF where clicking on a reference scrolls you to the corresponding biliography entry.

For instance [1] would be [<a href="#bibliography-entry-1>1</a>] and the corresponding entry would have id="bibliography-entry-1".

Thank you for the great work!

Possibly update parse-citation implementation

parse-citaiton.js was adapted from https://github.com/Zettlr/Citr/blob/master/lib/citr.ts but it seems that has now been archived and the new version is in https://github.com/Zettlr/Zettlr/blob/develop/source/common/util/extract-citations.ts.

Might be worth reviewing if any there are changes or improvements to port over.

Doesn't work with footnote CSL styles

I used the chicago-fullnote-bibliography.csl provided by Zotero as follows .use(rehypeCitation, {bibliography: "./writing/ml.bib", csl: "./csls/chicago-fullnote-bibliography.csl"}).

The library outputs this:

Default (no csl option passed): <span id="user-content-citation--wiggers_bigsciences_2022--1">(Wiggers 2022)</span>
Footnote (which chicago-fullnote csl option): <span id="user-content-citation--wiggers_bigsciences_2022--1">Kyle Wiggers, “BigScience’s AI Language Model Is Finally Available,” July 12, 2022, https://techcrunch.com/2022/07/12/a-year-in-the-making-bigsciences-ai-language-model-is-finally-available/.</span>

As you can see, rather than generating a numbered superscript with a link, it simply repeats the entire "fullnote" citation that should be in the footnote section.

It's rendered like this:

whereas pandoc does something like

<span
class="citation" data-cites="wiggers_bigsciences_2022"><a href="#fn1"
class="footnote-ref" id="fnref1"
role="doc-noteref"><sup>1</sup></a></span>

Bug in HTML generation when using 10 or more references with numeric style and linked citations

Issue

When using 10 or more distinct references in one file with a numeric style csl and linkCitations enabled the HTML generation breaks.

Steps to reproduce

Using the linkCitaion example from the demo app:

• use numeric citation style
• add up to 10 literature entries to bib file
• add up to diferent 10 references in markdown example text

Or simply checkout my fork.

Multiple citation are not separated and appear as one

In the case of having multiple citation, they are not picked up properly in the output with a proper separation (comma, dash or any custom separator) and appear as one concatenated citation.

Example:

LinkQA [@Gueret:ESWC:12][@Hogan:SSKB:06]

Instead of 99, 100 for example

refactor out parse5

parse5 which is used to convert html to hast brings contributes an additional 180kB to the bundle size and is the next easiest thing to remove. The ideal solution would probably use hast-util-from-dom for the browser and https://github.com/syntax-tree/hast-util-from-parse5 for node environment.

Div for inline citation

Hi, thanks for this great plugin! I was about to make my own when I found yours.

I'm looking to make a blog with a similar citation structure with distill.pub with hoverable bibliographies. The easiest way that I could think of is for inline citations to be enclosed in some div. The bibliographic information of those citations would be optionally appended right next to the citation with classes that can be specified in options.inlineBibClass. Would it be possible to add such feature? I could also try submitting a PR.

Thanks a lot!

TypeError: Cannot read properties of undefined (reading 'value')

If I use rehype-citation it fails with the following error message.

TypeError: Cannot read properties of undefined (reading 'value')

Cannot `process` without `Compiler`

Hi @timlrx,
This tool is exaclty what I need. However, I am running into the error Cannot processwithoutCompiler`` when running the app. Do you have an idea how to solve this issue?

Cannot redefine property: Cite

Hi I tried using rehype-citation (to help format some markdown files) in a Next.js 13.5.4 application like this:

rehype-citation version 0.2.0

import rehypeCitation from 'rehype-citation';
...
options.rehypePlugins = [
        ...(options.rehypePlugins ?? []),
        rehypeSlug,
        rehypeAutolinkHeadings,
        rehypeKatex,
        [rehypeCitation, { path: path.join(root, 'data') }],
        [rehypePrismPlus, { ignoreMissing: true }],
        rehypePresetMinify,
      ];
return options;

and get this error: Cannot redefine property: Cite

linkCitation uses wrong brackets

The current implementation always assumes that the csl style uses parentheses for the citation. But this is not always the case (e.g. acm-siggraph, ieee, ...).
The link insertion replaces the old brackets with wrong brackets in 'author-date' format with a single entry.

Style: ACM Siggraph:
Current implementation:
SLERP [@shoemake85] -> SLERP (Shoemake 1985)

Correct:
SLERP [@shoemake85] -> SLERP [Shoemake 1985]