@jxpeng98/markdown-it-citation

A markdown-it plugin to handle BibTeX citations and bibliography.

Features

• Parses @citekey in markdown text for parenthetical citations (e.g., (Author, Year)).
• Parses !@citekey in markdown text for narrative citations (e.g., Author (Year)).
• Supports defining citations in Frontmatter (YAML).
• Generates a bibliography at the end of the document.
• Uses citation-js for parsing and formatting.

Installation

npm install @jxpeng98/markdown-it-citation
# or
bun add @jxpeng98/markdown-it-citation

# also ensure markdown-it is installed
npm install markdown-it

This package declares markdown-it as a peer dependency.
Your project is expected to provide a compatible markdown-it instance:

• Required:
  • markdown-it (the host markdown parser)

In most setups (VitePress, VuePress, custom markdown-it pipelines), you already depend on markdown-it or the framework installs it for you. If you see a peer dependency warning, add markdown-it to your own dependencies/devDependencies.

Usage

import MarkdownIt from 'markdown-it';
import citationPlugin from '@jxpeng98/markdown-it-citation';

const md = new MarkdownIt();

md.use(citationPlugin, {
  bibFile: 'public/references.bib', // Path to your BibTeX/BibLaTeX file
  style: 'apa', // Citation style (apa, harvard1, vancouver, ieee, mla, chicago-author-date)
  showNum: false, // Set to true to enable numbered bibliography
  bibTitle: 'References', // Optional title for the bibliography section
  autoGenerate: false // Set to true to auto-generate bibliography at end (default: false)
});

const result = md.render('This is a citation @boland2007statistical.');

Bibliography Generation

By default, the bibliography is not automatically generated. You need to manually place the [[bibliography]] marker in your document where you want the bibliography to appear.

Manual Trigger (Recommended)

Place [[bibliography]] on its own line where you want the bibliography to appear:

This is a citation @boland2007statistical.

Some more content here.

## References

[[bibliography]]

This gives you full control over where the bibliography appears, which is especially useful for:

• Slidev presentations (place bibliography on a dedicated slide)
• Multi-section documents
• Custom layouts

Auto-Generate Mode

If you prefer the old behavior of auto-appending the bibliography at the end of the document, set autoGenerate: true:

md.use(citationPlugin, {
  bibFile: 'public/references.bib',
  autoGenerate: true // Auto-generate bibliography at end if no [[bibliography]] marker found
});

Note: If [[bibliography]] marker is present in the document, it will be used regardless of the autoGenerate setting.

Frontmatter Support

You can list citations in the frontmatter to include them in the bibliography even if they are not explicitly cited in the text.

---
citations:
  - @boland2007statistical
  - @kaas2008modern
---

Content here...

Supported keys in frontmatter: citations, references, bib.

Styles

Minimal CSS to style the citations and bibliography:

/* In-text citation */
.citation {
  color: #007bff;
  cursor: pointer;
}

.citation-error {
  color: red;
  font-weight: bold;
}

/* Bibliography container */
.bibliography {
  margin-top: 2em;
  border-top: 1px solid #eee;
  padding-top: 1em;
}

/* Individual entry (CSL output) */
.csl-entry {
  margin-bottom: 0.5em;
}

Testing

To run the tests, use the following command:

bun test
# or
bun run test

This will run the test script test/run.ts which verifies:

• In-text citations
• Frontmatter citations
• Mixed citations
• Bibliography generation

You can also test different styles using:

bun test/test-styles.ts