micromark-extension-cite
A micromark syntax extension for pandoc-style citations, providing the low-level modules for integrating with the micromark tokenizer and the micromark HTML compiler.
You probably shouldn’t use this package directly, but instead use mdast-util-cite with mdast or remark-cite with remark.
Install
Install @benrbray/micromark-extension-cite on npm.
npm install @benrbray/micromark-extension-cite
Usage
import micromark from "micromark";
import { citeSyntax, citeHtml } from "micromark-extension-cite";
let serialized = micromark('[see @wadler1989, sec. 1.3; and @hughes1990, pp.4]', {
extensions: [citeSyntax()],
htmlExtensions: [citeHtml()]
});The serialized result will be the following. To get an abstract syntax tree, use mdast-util-cite instead.
<p><span class="citation" data-cites="wadler1989 hughes1990">
[see @wadler1989, sec. 1.3; and @hughes1990, pp.4]
</span></p>Configuration Options
options.enablePandocSyntax [boolean]
Enable the pandoc-style syntax, [@wadler1989]. A single citation can cite multiple items, and each individual item can have a prefix and suffix. The default is true. Authors can be suppressed with a hyphen -.
options.enableAltSyntax [boolean]
Enable the alternative syntax, @[wadler1989]. A single citation can site multiple items, but the first item cannot have a prefix. Authors can be suppressed with a hyphen -.
Syntax
By default, this extension supports pandoc-style syntax, where each citation item can have a prefix, suffix, and key. Include a hyphen - before an @ symbol to indicate that the author name should be suppressed.
[@wadler1989:comprehending-monads]
[see @wadler1989, pp. 80; and @hughes1990; also @peyton-jones2003]
[-@wadler1989; and @hughes1990]
With the enableAltSyntax option, you can place the first @ symbol before the opening bracket. When using the alternative syntax, the first item cannot have a prefix. The first item can be suppressed with a leading hyphen -.
@[wadler1989:comprehending-monads]
@[wadler1989, pp. 80; and @hughes1990; but don't forget @peyton-jones2003]
@[-wadler1989; and @hughes1990]
Railroad Diagrams
A micromark syntax extension is basically a state machine that operates on a character stream to produce a stream of tokens that can later be assembled into a syntax tree by mdast. The following diagrams, produced by grammkit, give a rough sketch of the state machine:
Pandoc Syntax
Alternate Syntax
Of course, since the code for this extension was written by hand, rather than by a parser generator, the correspondence is not exact. A future project might be to convert PEG grammars to micromark syntax extensions, in an attempt to escape the third and fourth certainties in life: bugs and boilerplate. :)
Differences from pandoc
Mostly to reduce complexity, the syntax supported by this extension differs from pandoc citation syntax in the following ways:
- To avoid recognizing email addresses as citations, we require the prefix, when it exists, to end with a space character.
- Unlike Pandoc, we make no distinction between the "locator" and "suffix".
These choices are not set in stone, so feel free to open an issue to discuss possible changes.