Plugins Citations

cite and cross-reference @mdsvex/plugin-citations@0.1.0-next.1

Citations

Citations, :cite[key] from a CSL JSON bibliography and a ::bibliography that lists what a document cites

Install

pnpm add -D @mdsvex/plugin-citations@next

Turn it on

import { citations } from '@mdsvex/plugin-citations';

mdsvex({ plugins: [citations()] });

It waits, as it reads the bibliography the frontmatter names: the Vite plugin and compile_async compile such a document, compile throws a PluginAsyncError.

What it reads

:cite[key] ::bibliography

owns cite, bibliography · reads the whole document

An example

You write
---
bibliography: ./refs.json
---

The engine could do more than count :cite[lovelace1843].

::bibliography[References]

and the file it reads, ./refs.json
[{"id": "lovelace1843", "type": "article-journal", "title": "Notes on the Analytical Engine", "author": [{"family": "Lovelace", "given": "Ada"}], "container-title": "Scientific Memoirs", "issued": {"date-parts": [[1843]]}}]
You get

The engine could do more than count [1].

References

  1. Ada Lovelace. Notes on the Analytical Engine. Scientific Memoirs. 1843. ↩︎
Build-time preview.

Cites entries of a CSL JSON file, which the frontmatter names, and lists the entries the document cites where you write ::bibliography:

---
bibliography: ./refs.json
---

The engine could do more than count :cite[lovelace1843], as was later proved :cite[turing1936, lovelace1843].

::bibliography[References]
<p>
	The engine could do more than count
	<span class="citation">[<a href="#bib-lovelace1843" id="cite-1" role="doc-biblioref">1</a>]</span>,
	as was later proved
	<span class="citation">[<a href="#bib-turing1936" id="cite-2" role="doc-biblioref">2</a>,
	<a href="#bib-lovelace1843" id="cite-3" role="doc-biblioref">1</a>]</span>.
</p>
<section role="doc-bibliography" aria-labelledby="s1-label" class="bibliography">
	<p class="bibliography-label" id="s1-label">References</p>
	<ol>
		<li id="bib-lovelace1843">
			Ada Lovelace. <cite>Notes on the Analytical Engine.</cite> Scientific Memoirs 3, 666-731. 1843.
			<a href="#cite-1" role="doc-backlink" aria-label="Back to citation 1">↩︎</a>
			<a href="#cite-3" role="doc-backlink" aria-label="Back to citation 3">↩︎</a>
		</li>
		<li id="bib-turing1936">...</li>
	</ol>
</section>
citations({
	bibliography: string, // the file of a document whose frontmatter names none
	style: 'numeric' | 'author-date' = 'numeric'
});
  • :cite[key] cites one entry and :cite[a, b] several, by the id of each in the file. Each key links to its entry and each entry links back to every citation of it.
  • style is numeric, [1] and a list numbered by first citation, or author-date, (Lovelace 1843; Turing 1936) and a list by author.
  • The file is the bibliography key of the frontmatter, relative to the document, or the bibliography option, absolute or relative to the working directory. It is read once for every document and read again when it changes, in the dev server too. A document that cites with no file named fails with a CitationsError.
  • An unknown key is a warning at the citation, which shows the key as written, without a link.
  • BibTeX is not read. Zotero, JabRef and pandoc refs.bib -t csljson -o refs.json export CSL JSON.

The citations and their entries are plugin data, plugin_data.citations, so a template can render the list itself with the Bibliography component:

<script>
	import Bibliography from '@mdsvex/plugin-citations/Bibliography.svelte';
	let { plugin_data, children } = $props();
</script>

{@render children()}
<Bibliography data={plugin_data?.citations} />

The file is read while the document compiles, so the Vite plugin and compile_async take a document that cites, and compile throws a PluginAsyncError. compile_async needs the document's filename, to find the file the frontmatter names, and a read option, to load it:

import { readFile } from 'node:fs/promises';
import { compile_async } from 'mdsvex/compile';
import { citations } from '@mdsvex/plugin-citations';

// ./refs.json in the frontmatter is /site/refs.json
const { code, data } = await compile_async(source, {
	filename: '/site/post.svx',
	read: (file) => readFile(file, 'utf8'),
	plugins: [citations()]
});

For a custom list, bibliography_of(plugin_data.citations, style) gives the entries in the order the list shows them, each with its id, its label and the ids of the citations of it in cited_by. entry_parts(entry, style) splits an entry into the pieces of its text, each { kind, text } with kind one of text, title or url. entry_id(key) and citation_id(n) are the ids the plugin gives a list item and the nth citation, from 0, so links match the ones it renders. All four come from @mdsvex/plugin-citations.

The formatting is small on purpose: names, year, title, where it was published, the publisher and a link. Citation styles such as APA or Chicago, locators like page numbers, and telling apart two works of one author in one year need a full CSL processor.

Options, from its types 2

bibliography?: string
The CSL JSON file a document cites from when its frontmatter names none, absolute or relative to the working directory
style?: CitationStyle
`numeric` by default, `[1]` and a numbered list, `author-date` is `(Lovelace 1843)` and a list by author

mdsvex, markdown with Svelte in it. MIT licence.