MDJ - Markdown (GFM) to JSON compiler
Because sometimes you don't need HTML.
Why
I needed small, reasonably performant, extendable and reliable tool to convert Markdown (GFM) to JSON. Every small markdown parser, that I've found, couldn't generate JSON; every module, capable of generating JSON, is insanely bloated. Therefore I decided to make my own. MDJ is mostly based on marked with many improvements.
Usage
import MDJ from 'mdj'
import source from 'source.md'
const mdj = MDJ()
const parsedSource = mdj.parse(source)
// OR
import { parse } from 'mdj'
import source from 'source.md'
const parsedSource = parse(source) // Note that this is less performant.
MDJ constructor accepts an optional settings argument:
interface IMDJOptions {
html?: boolean // enables HTML support, false by default
}
Output
Parser returns an array of tokens. Each token contains at least one property - type
, which can be heading
, paragraph
, code
etc.
Other content of tokens may vary. For example tokens of types text
, code
, codeblock
and html
have a value
property, which represents the raw content of that token.
const md = '`console.log("test")`'
parse(md) //
/*
outputs
[
{
type: 'paragraph',
children: [
{
type: 'code',
value: 'console.log("test")
}
]
}
]
*/
As you would have noticed, other tokens may have the children
property, which will contain another array of tokens.
Adding new parser rules
Parsers are divided into two parts:
- Block parsers, e.g.: paragraph, lists, tables, block quotes etc.
- Inline parsers, e.g.: links, checkboxes, images, etc.
To add new parser rule use corresponding instance method:
const blockParser = (source: string) => {/* */}
const inlineParser = (source: string) => {/* */}
const priority = 300
mdj.useBlockParser(blockParser, priority)
mdj.useInlineParser(inlineParser, priority)
Before starting the parsing process all rules are sorted by priority. You may check priorities of default parsers in the source (./src/core/MDJ.ts
)
Each parser receives from one to three parameters - source
, which is, basically, non-parsed part of the initial source, and one or two lexers (block-level and inline-level for block-level parsers and only inline-level lexer for inline-level parser). Passed lexers use the same MDJ instance and can be used to parse whatever needs to be parsed inside your parser.
Parser should return null, if it did nothing, or an object, containing a new token, which will be added to JSON and a new source. See examples in ./src/parsers
.
Roadmap to 1.0.0:
Support:
- Reference links and images
- HTML
- Checkbox lists
Performance:
- Add public benchmarks
- Move to rollup
- Try prepack.io - tried, no benefit
License
MDJ is released under the MIT license.