npm package: @jxpeng98/markdown-it-citation
Description: A markdown-it plugin for citations and bibliography
Author: Jiaxin Peng
Latest version: 1.2.1

# @jxpeng98/markdown-it-citation

A [markdown-it](https://github.com/markdown-it/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](https://citation.js.org/) for parsing and formatting.

## Installation

```bash
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

```typescript
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:

```markdown
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`:

```typescript
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.

```markdown
---
citations:
  - @boland2007statistical
  - @kaas2008modern
---

Content here...
```

Supported keys in frontmatter: `citations`, `references`, `bib`.

## Styles

Minimal CSS to style the citations and bibliography:

```css
/* 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:

```bash
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:

```bash
bun test/test-styles.ts
```