cite and cross-reference @mdsvex/plugin-citations
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 directive ::bibliographyowns cite, bibliography · reads the whole document
An example
--- 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]]}}]
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 theidof each in the file. Each key links to its entry and each entry links back to every citation of it.styleisnumeric,[1]and a list numbered by first citation, orauthor-date,(Lovelace 1843; Turing 1936)and a list by author.- The file is the
bibliographykey of the frontmatter, relative to the document, or thebibliographyoption, 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 aCitationsError. - 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.jsonexport 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.