@microflash/fenceparser

fenceparser

A metadata parser for code fences in markdown

Contents

• Contents
• What’s this?
• Install
• Use
• API
  • Syntax
• Examples
  • Example: single range
  • Example: multiple ranges
  • Example: ranges with custom annotations
  • Example: key-value pairs
• Development
• License

What’s this?

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, (e.g., {1} {3, 7} ins{9-11, 88} del{90, 101..167}) and
• key-value pairs (e.g., caption='Hello, World')

Install

This package is ESM only.

In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install @microflash/fenceparser

In Deno, with esm.sh:

import fenceparser from 'https://esm.sh/@microflash/fenceparser'

In browsers, with esm.sh:

<script type="module">
  import fenceparser from 'https://esm.sh/@microflash/fenceparser?bundle'
</script>

Use

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.

{
  "lang": "js",
  "meta": "{1} {3, 7} {9-11, 88} {90, 101..112} text-color='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"
}

Use the fenceparser to parse the meta as follows.

import parse from '@microflash/fenceparser'

console.log(parse("{1} {3, 7} {9-11, 88} ins{90, 101..112} text-color='--text-default' syntax_theme=\"nord\" css=`{ *: { display: none }}`"))

Running the above example yields.

{
  'text-color': '--text-default',
  syntax_theme: 'nord',
  css: '{ *: { display: none }}',
  highlight: [
      1,   3,   7,   9,  10,  11,
     88,  
  ],
  ins: [
     90, 101, 102, 103, 104, 105,
    106, 107, 108, 109, 110, 111, 
    112,
  ]
}

API

The default export is parse.

Syntax

Key-value pairs

• The key and value must be separated by equality sign =.
• The value must be wrapped within single-quotes ', double-quotes " or backticks `.

Ranges

• A range can be a single number, or a pair of numbers denoting the start and end values separated by either a hyphen - or double-dots ...
• A range must be wrapped in curly braces.
• Multiple ranges can be wrapped 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 highlight.
• Multiple ranges will be grouped in a single array by their annotations.

Examples

Example: single range

import parse from '@microflash/fenceparser'

console.log(parse("{100}"))

Running the above example yields.

{
  highlight: [
    100,
  ]
}

Example: multiple ranges

import parse from '@microflash/fenceparser'

console.log(parse("{3, 7} {9-11, 101..105}"))

Running the above example yields.

{
  highlight: [
      1,   3,   7,   9,  10,  11,
    101, 102, 103, 104, 105,
  ],
}

Example: ranges with custom annotations

import parse from '@microflash/fenceparser'

console.log(parse("{3, 7} ins{9-11, 13} del{101..105}"))

Running the above example yields.

{
  highlight: [
      3,   7,
  ],
  ins: [
      9,  10,  11,  13,
  ],
  del: [
    101, 102, 103, 104, 105,
  ],
}

Example: key-value pairs

import parse from '@microflash/fenceparser'

console.log(parse("data-theme='synthwave' callback=`(code) => copyToClipboard(code)`"))

Running the above example yields.

{
  'data-theme': 'synthwave',
  callback: '(code) => copyToClipboard(code)',
}

Check the fixtures for more examples on the syntax.

Development

Any changes in the lexer or parser should have corresponding tests.

Run the tests with the following command.

npm test

License

MIT