@bernardjoseph/mdast-util-citekey
v0.1.1
Published
mdast extension to parse and serialize Pandoc-style citation keys
Downloads
16
Maintainers
Readme
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 import
ed instead of require
d.
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 pluginsmicromark/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 keyssyntax-tree/mdast-util-from-markdown
— mdast parser usingmicromark
to create mdast from markdownsyntax-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