A markdown-it plug-in for rendering citations and a bibliography inside markdown.
Through NPM:
npm i -s @arothuis/markdown-it-biblatex
In your project, add this plugin to markdown-it:
const markdownIt = require('markdown-it');
const mdBiblatex = require('@arothuis/markdown-it-biblatex');
const md = markdownIt();
md.use(mdBiblatex, {
bibPath: 'path/to/example.bib',
});Imagine that our path/to/example.bib contains the following
references. This is parsed using
biblatex-csl-converter
@article{Cohen-1963,
author = "P. J. Cohen",
title = "The independence of the continuum hypothesis",
journal = "Proceedings of the National Academy of Sciences",
year = 1963,
volume = "50",
number = "6",
pages = "1143--1148",
}
@book{Susskind-Hrabovsky-2014,
author = "Leonard Susskind and George Hrabovsky",
title = "Classical mechanics: the theoretical minimum",
publisher = "Penguin Random House",
address = "New York, NY",
year = 2014
}
@booklet{Swetla-2015,
title = "Canoe tours in {S}weden",
author = "Maria Swetla",
howpublished = "Distributed at the Stockholm Tourist Office",
month = jul,
year = 2015
}
If we render the following markdown:
A bibliography [@Cohen-1963] is only produced for
the items cited [@Susskind-Hrabovsky-2014].
[bibliography]It produces the following HTML thanks to the power of citeproc-js:
<p>
A bibliography (Cohen, 1963) is only produced for the items cited (Susskind & Hrabovsky,
2014).
</p>
<div class="bibliography">
<h2 class="bibliography-title">Bibliography</h2>
<div class="bibliography-contents">
<div class="csl-entry">
Cohen, P. J. (1963). The independence of the continuum hypothesis.
<i>Proceedings of the National Academy of Sciences</i>, <i>50</i>(6), 1143–1148.
</div>
<div class="csl-entry">
Susskind, L., & Hrabovsky, G. (2014). <i>Classical mechanics: the theoretical minimum</i>.
New York, NY: Penguin Random House.
</div>
</div>
</div>Note that only actually cited items are included in the printed bibliography. For more extensive examples, have a look at the test cases.
We can add a prefix to a citation, by wrapping it in curly braces:
[@Cohen-1963{see}]Results in:
<p>(see Cohen, 1963)</p>If you want to specify a specific location within a certain
citation, you can use the locator mark (#):
[@Cohen-1963#p. 3]
[@Cohen-1963#p. 3{see}]Result:
<p>(Cohen, 1963, p. 3)</p>
<p>(see Cohen, 1963, p. 3)</p>Through citeproc, we support several citation forms. In this plugin, we use special marks in front of the @-sign:
- author only(
!): render only the author of the item or its title if there is none - suppress author(
-): render the citation omitting the author, or its title if there is none - composite(
~): a combination of author only and suppress author, typically used for in-line citations
This is illustrated as follows:
### Regular
A regular citation: [@Cohen-1963]
### Author only
A citation with the author only: [!@Cohen-1963]
### Suppress author
A citation with the author suppressed: [-@Cohen-1963]
### Composite
A composite citation: [~@Cohen-1963]This produces the following HTML, when processing citations using an en-US locale and the APA style:
<h3>Regular</h3>
<p>A regular citation: (Cohen, 1963)</p>
<h3>Author only</h3>
<p>A citation with the author only: Cohen</p>
<h3>Suppress author</h3>
<p>A citation with the author suppressed: (1963)</p>
<h3>Composite</h3>
<p>A composite citation: Cohen (1963)</p>It is possible to reference multiple sources in a single
citation, by using a semicolon (;):
[@Cohen-1963; @Susskind-Hrabovsky-2014].This outputs the following:
<p>(Cohen, 1963; Susskind & Hrabovsky, 2014).</p>Since we support multiple bibliographies, ordering has become relevant: each bibliography only contains the references that came directly before it. This means that, currently, a bibliography cannot appear before the references.
The following options can be passed to the plug-in (defaults shown).
Only bibPath is required.
{
// Where to find the biblatex file (.bib)
bibPath: null,
// Change locale for displaying references and bibliography (.xml)
// See: https://github.com/citation-style-language/locales
localePath: __dirname + "/csl/locales-en-US.xml",
// Change citation style for displaying references and bibliography (.csl)
// See: https://github.com/citation-style-language/styles
stylePath: __dirname + "/csl/apa-6th-edition.csl",
// Which mark to use for suppress-author (don't show author)
suppressAuthorMark: "-",
// Which mark to use for author-only (only show author)
authorOnlyMark: "!",
//Which mark to use for composite (inline text citation, i.e. without parentheses)
compositeMark: "~",
// Which mark to use to signify an infix text for composite citations
infixMark: "^",
// Mark for placement of bibliography layout
// (choose carefully to prevent collissions with other tokens)
bibliographyMark: "[bibliography]",
// Replace bibliography title element
bibliographyTitle: '<h2 class="bibliography-title">Bibliography</h2>',
// Wrap bibliography in a div
wrapBibliography: true,
// Element that wraps bibliography contents
bibliographyContentsWrapper: "div",
// Element that wraps bibliography entry
bibliographyEntryWrapper: "div"
};If you want more extensive control over how the output is rendered, you can overwrite the following renderer rules with your own functions after adding the plug-in to markdown-it:
md.renderer.rules.biblatex_reference = function (tokens, idx, options, env, slf) {};
md.renderer.rules.biblatex_bibliography_open = function (tokens, idx, options, env, slf) {};
md.renderer.rules.biblatex_bibliography_contents = function (tokens, idx, options, env, slf) {};
md.renderer.rules.biblatex_bibliography_close = function (tokens, idx, options, env, slf) {};Have a look at the source code of this plug-in and the markdown-it docs for more information.
This plug-in works similar yet different to:
Their approaches are comparable, but did not fit my needs.