@bernardjoseph/micromark-extension-citekey NPM

micromark-extension-citekey

micromark extension to support Pandoc-style citation keys.

When to use this

If you’re using micromark or mdast-util-from-markdown, use this package. Alternatively, if you’re using remark, use remark-citekey.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install @bernardjoseph/micromark-extension-citekey

Use

Say we have the following file, example.md:

@wadler1989. @{hughes1990.}

And our script, example.js, looks as follows:

import fs from 'node:fs'
import {micromark} from 'micromark'
import {citekey, citekeyHtml} from '@bernardjoseph/micromark-extension-citekey'

const out = micromark(fs.readFileSync('example.md'), {
  extensions: [citekey()],
  htmlExtensions: [citekeyHtml]
})

console.log(out)

Now, running node example yields:

<p><span class="citekey">@<span class="citeid=">wadler1989</span></span>. <span class="citekey">@{<span class="citeid=">hughes1990.</span>}</span></p>

API

This package exports the following identifiers: citekey, citekeyHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

`citekey(options?)`

Function that can be called with options to get an extension for micromark to parse Pandoc-style citation keys (can be passed in extensions).

`options.strict`

A boolean option to restrict citation keys to ASCII.

If set to true, citation keys end at the first non-ASCII character. For example, running the script:

import {micromark} from 'micromark'
import {citekey, citekeyHtml} from '@bernardjoseph/micromark-extension-citekey'

const out = micromark('@müller', {
  extensions: [citekey({strict: true})],
  htmlExtensions: [citekeyHtml]
})

console.log(out)

Yields:

<p><span class="citekey">@<span class="citeid=">m</span></span>üller</p>

The default value is false.

`citekeyHtml`

Extension for micromark to compile Pandoc-style citation keys to HTML (can be passed in htmlExtensions).

Caveats

Labeled item markers of Pandoc numbered example lists look like Pandoc-style citation keys:

(@good) This is a good example.

As (@good) illustrates, ...

Currently, there exists no micromark extension for Pandoc numbered example lists. Without such an extension, all labeled item markers are parsed as citation keys.

Syntax

The syntax of Pandoc-style citation keys is described in the Pandoc manual.

The Pandoc manual does not specify what characters are allowed to precede a citation key. This extension imitates the behavior of the Pandoc parser and allows all characters except alphanumerics and periods to precede a citation key.

remarkjs/remark — markdown processor powered by plugins
remark-citekey — remark plugin to support citation keys
micromark/micromark — the smallest commonmark-compliant markdown parser that exists
mdast-util-citekey — mdast utility to support citation keys
syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast