A metadata parser for code fences in markdown
npm install @microflash/fenceparser
A metadata parser for code fences in markdown
- What’s this?
- Install
- Use
- API
- Options
- Syntax
- Examples
- Example: single range
- Example: multiple ranges
- Example: ranges with custom annotations
- Example: key-value pairs
- Example: customizing the default range key
- Development
- License
Many markdown processors can parse the language token associated with a code fence. fenceparser is meant for parsing other metadata besides language token. It supports
- ranges, (for example, {1} {3, 7} ins{9..11, 88} del{90, 101..167}) and
- key-value pairs (for example, caption='Hello, World')
This package is ESM only.
In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
``sh`
npm install @microflash/fenceparser
In Deno, with esm.sh:
`js`
import parse from "https://esm.sh/@microflash/fenceparser";
In browsers, with esm.sh:
`html`
Say, you have the following code fence
`js {1} {3, 7} {9..11, 88} {90, 101..112} text-color='--text-default' syntax_theme="nord" css={ *: { display: none }}
remark will provide the meta and lang for the above code fence.
`json{ *: { display: none }}
{
"lang": "js",
"meta": "{1} {3, 7} {9..11, 88} {90, 101..104} text-color='--text-default' os=\"macOS 26 Tahoe\" syntax_theme=nord css="`
}
Use the fenceparser to parse the meta as follows.
`js
import parse from "@microflash/fenceparser";
const metadata = parse("{1} {3, 7} {9..11, 88} {90, 101..104} text-color='--text-default' os=\"macOS 26 Tahoe\" syntax_theme=nord css={ *: { display: none }}");`
console.log(metadata);
Running the above example yields.
`js`
{
'*': [
1, 3, 7, 9, 10,
11, 88, 90, 101, 102,
103, 104
],
'text-color': '--text-default',
os: 'macOS 26 Tahoe',
syntax_theme: 'nord',
css: '{ *: { display: none }}'
}
The default export is parse function.
The following options are available. All of them are optional.
- rangeKey (default: *): specifies the range key to group ranges without annotations
#### Key-value pairs
- The key and value must be separated by equality sign =.'
- The value can be unquoted if there are no spaces, else it must be wrapped in single-quotes , double-quotes " or backticks `.
- The key can contain letters, numbers, underscore, hyphen, and dollar sign.
#### Ranges
- A range can be a single number, or a pair of numbers denoting the start and end values separated by double-dots ...,
- A range must be specified in curly braces.
- Multiple ranges can be specified in a single pair of curly braces. They should be separated by comma .*
- Ranges can also be annotated; the annotation should be prefixed before the starting curly brace. The default annotation is . You can customize this annotation by passing rangeKey value in the options.
- Ranges will be grouped in a single array by their annotations.
`js
import parse from "@microflash/fenceparser";
console.log(parse("{100}"));
`
Running the above example yields.
`js`
{
'*': [ 100 ]
}
`js
import parse from "@microflash/fenceparser";
console.log(parse("{3, 7} {9..11, 101..105}"));
`
Running the above example yields.
`js`
{
'*': [
3, 7, 9, 10, 11,
101, 102, 103, 104, 105
]
}
`js
import parse from "@microflash/fenceparser";
console.log(parse("{3, 7} ins{9..11, 13} del{101..105}"));
`
Running the above example yields.
`js`
{
'*': [ 3, 7 ],
ins: [ 9, 10, 11, 13 ],
del: [ 101, 102, 103, 104, 105 ]
}
`js
import parse from "@microflash/fenceparser";
console.log(parse("data-theme=synthwave callback=(code) => copyToClipboard(code)"));`
Running the above example yields.
`js`
{
'data-theme': 'synthwave',
callback: '(code) => copyToClipboard(code)'
}
`js
import parse from "@microflash/fenceparser";
console.log(parse("{100, 102}", { rangeKey: "highlight" }));
`
Running the above example yields.
`js`
{
highlight: [ 100, 102 ]
}
Check the fixtures for more examples on the syntax.
Any changes in the parser should have corresponding tests.
Run the tests with the following command.
`sh``
pnpm test