rehype plugin to add citation and bibliography from bibtex files
npm install 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
- Citations with Bibliography
- Suppress Bibliography
- Custom CSL
- Footnote style
- Link Citations
- Tooltips
This package is ESM only:
Node 12+ is needed to use it and it must be imported instead of required.
``js`
npm install rehype-citation
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:
`js
import rehype from 'rehype'
import rehypeCitation from 'rehype-citation'
rehype().use(rehypeCitation).process(/ some html /)
`
Input:
`md`
My markdown text [@Nash1950]
HTML Output:
`html`My markdown text (Nash, 1950)
Nash, J. (1950). Equilibrium points in n-person games.
Proceedings of the National Academy of Sciences, 36(1), 48–49.
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.
`js
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)
`
rehype().use(rehypeCitation, [options])
If no bibliography file is passed, the plugin will be skipped.
#### 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.process.cwd()
Default: .
Required, path to file. Will be joined with options.bibliography and options.csl, if provided.
#### options.csl
Type: 'apa'|'vancouver'|'harvard1'|'chicago'|'mla'|string.apa
Default: .
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. Can also be specified as a frontmatter option in the markdown file to override the default.
#### options.lang
Type: string.en-US
Default: .
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.false
Default: .
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. Can also be specified as a frontmatter option in the markdown file.
#### 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.false
Default: .
If true, citations will be hyperlinked to the corresponding bibliography entries (for author-date and numeric styles only).
#### options.showTooltips
Type: boolean.false
Default: .
If true, citations will display tooltips containing the full bibliography entry when hovered. For multiple citations, each reference will have its own tooltip. When used with linkCitations: true, tooltips are added to each individual link.
#### options.tooltipAttribute
Type: string.title
Default: .
The HTML attribute to use for tooltips. By default, the standard HTML title attribute is used, but you can specify an alternative attribute (e.g., data-tooltip`) for custom tooltip implementations or to work with specific tooltip libraries.