Nanananananananana.. Pat Man!

    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published


    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 @benrbray/micromark-extension-cite on npm.

    npm install @benrbray/micromark-extension-cite 


    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]

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


    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.

    [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, 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

    pandoc syntax

    Alternate 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.


    npm i @benrbray/micromark-extension-cite

    DownloadsWeekly Downloads






    Unpacked Size

    140 kB

    Total Files


    Last publish


    • avatar