mdast-util-citekey

Extension for mdast-util-from-markdown and mdast-util-to-markdown to support Pandoc-style citation keys in mdast.

When to use this

Use this if you’re dealing with the AST manually. It might be better to use remark-citekey with remark, which includes this but provides a nicer interface and makes it easier to combine with hundreds of plugins.

Install

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

npm:

npm install mdast-util-citekey

Use

Say our module, example.js, looks as follows:

import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {citekey} from 'micromark-extension-citekey'
import {citekeyFromMarkdown, citekeyToMarkdown} from '@bernardjoseph/mdast-util-citekey'

const doc = 'See @wadler1989, sec. 1.3, and @{hughes1990.}, pp. 4.'

const tree = fromMarkdown(doc, {
  extensions: [citekey()],
  mdastExtensions: [citekeyFromMarkdown]
}).children[0]

console.dir(tree, {depth: null})

const out = toMarkdown(tree, {extensions: [citekeyToMarkdown]})

console.log(out)

Now, running node example yields (positional info removed for brevity):

{
  type: 'paragraph',
  children: [
    {
      type: 'text',
      value: 'See '
    },
    {
      type: 'citekey',
      children: [
        {
          type: 'citekeyMarker',
          value: '@'
        },
        {
          type: 'citekeyId',
          value: 'wadler1989'
        }
      ]
    },
    {
      type: 'text',
      value: ', sec. 1.3, and '
    },
    {
      type: 'citekey',
      children: [
        {
          type: 'citekeyMarker',
          value: '@'
        },
        {
          type: 'citekeyStart',
          value: '{'
        },
        {
          type: 'citekeyId',
          value: 'hughes1990.'
        },
        {
          type: 'citekeyEnd',
          value: '}'
        }
      ]
    },
    {
      type: 'text',
      value: ', pp. 4.'
    }
  ]
}

See @wadler1989, sec. 1.3, and @{hughes1990.}, pp. 4.

API

citekeyFromMarkdown

citekeyToMarkdown

Support Pandoc-style citation keys. The exports are extensions for mdast-util-from-markdown and mdast-util-to-markdown, respectively. See the citation syntax section of the Pandoc manual for the syntax of Pandoc-style citation keys.

This utility handles parsing and serializing. Traverse the tree to change them to whatever you please.

Syntax tree

The following Nodes are added to mdast by this utility.

Nodes

interface Citekey extends Parent {
  type: 'citekey'
  children: Array<CitekeyMarker | CitekeyStart | CitekeyId | CitekeyEnd>
}

interface CitekeyMarker extends Literal {
  type: 'citekeyMarker'
}

interface CitekeyStart extends Literal {
  type: 'citekeyStart'
}

interface CitekeyId extends Literal {
  type: 'citekeyId'
}

interface CitekeyEnd extends Literal {
  type: 'citekeyEnd'
}

Citekey, CitekeyMarker, CitekeyStart, CitekeyId and CitekeyEnd (Literal) can be used where phrasing content is expected.

For example, the following Markdown:

'@wadler1989

Yields:

{
  type: 'citekey',
  children: [
    {
      type: 'citekeyMarker',
      value: '@'
    },
    {
      type: 'citekeyId',
      value: 'wadler1989'
    }
  ]
}

And the following Markdown:

'@{hughes1990.}

Yields:

{
  type: 'citekey',
  children: [
    {
      type: 'citekeyMarker',
      value: '@'
    },
    {
      type: 'citekeyStart',
      value: '{'
    },
    {
      type: 'citekeyId',
      value: 'hughes1990.'
    },
    {
      type: 'citekeyEnd',
      value: '}'
    }
  ]
}

Related

• remarkjs/remark — markdown processor powered by plugins
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• @bernardjoseph/remark-citekey — remark plugin to support citation keys
• @bernardjoseph/micromark-extension-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

Contribute

See contributing.md in micromark/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Bernd Rellermeyer