Tiny Markdown to JSON Parser

Tiny Md Parser is a lightweight, extendable markdown to JSON parser that can be easily customized to support custom markdown elements. It seamlessly integrates with build tools, enabling the creation of markdown components for frameworks like React, Vue, and more. Additionally, it supports CDN links in HTML, allowing for browser-based JavaScript functionality.

We are trying to confirm to commonMark specs. Some of the APIs might change!

At this time, source code may only be available to the sponsors.

Please consider starring this repository and sharing it with your friends.

Getting Started

Installation

pnpm add @tinymd/md2json

or

npm install @tinymd/md2json

or

yarn add @tinymd/md2json

Usage

import { md2json, type Element } from "@tinymd/md2json";

// returns array of blocks
const blocks: Element[] = md2json(markdownString);

Options

export interface Md2JsonOptions {
  skipRanks?: number[];
  skipTags?: ElementTag[];
  blockParsers?: BlockParser[];
  inlineParsers?: InlineParser[];
}

Types - Useful for Extending Functionality

export type ElementTag =
  // block elements
  | "h1"
  | "h2"
  | "h3"
  | "h4"
  | "h5"
  | "h6"
  | "pre"
  | "blockquote"
  | "hr"
  | "ul"
  | "ol"
  | "li"
  | "p"
  // inline elements
  | "code"
  | "a"
  | "img"
  | "strong"
  | "em"
  | "span"
  | "small"
  | "s"
  | "u"
  | "br";

export type Attribute = "href" | "src" | "alt" | "class" | "title";
export type Props = Partial<Record<Attribute, string>>;

export interface Element {
  tag: ElementTag;
  contents: (string | Element)[];
  props?: Props;
  info?: string;
}

export type References = Record<string, Props>;

/** The parser function that returns void|undefined if no match is found,
 * or returns contents and linesConsumed as a tuple. */
export type BlockParserFunction = (
  lines: string[],
  currentIndex: number,
  references?: References,
  blockParsers?: BlockParser[],
) => [content: (string | Element)[], linesConsumed: number] | undefined;

/** Parser to parse block elements from markdown based on commonmark specs @see [commonmark specs](https://spec.commonmark.org/0.31.2/) */
export type BlockParser = [
  /** Rank 0 will have the highest priority.
   * Parsers will be evaluated in order of rank. */
  rank: number,
  /** The parser function that returns void|undefined if no match is found,
   * or returns contents and linesConsumed as a tuple. */
  parser: BlockParserFunction,
  /** HTML tag */
  tag: ElementTag,
];

export type InlineParserFunction = (
  blocks: (Element | string)[],
  parsers: InlineParser[],
  references: Record<string, Props>,
) => void;

export type InlineParser = [
  /** Rank 0 will have the highest priority.
   * Parsers will be evaluated in order of rank. */
  rank: number,
  /** Parser function */
  parser: InlineParserFunction,
  /** HTML tag - used to skip skipTags */
  tag?: ElementTag,
];

License

This library is licensed under the MPL-2.0 open-source license.

Please consider enrolling in our courses or sponsoring our work.