@croct/md-lite

MD Lite
A minimalist Markdown parser and render for basic formatting.

📦 Releases · 🐞 Report Bug · ✨ Request Feature

Introduction

This library provides a fast and simple Markdown parser with zero dependencies. Perfect for those who need to handle basic Markdown syntax without the overhead of a full-featured Markdown parser.

Features

• 🪶 Lightweight: Zero dependencies, under 5 KB gzipped.
• 🌐 Cross-environment: Works in Node.js and browsers.
• ✍️ Minimalist: Supports only italic, bold, strikethrough, inline code, links, 🖼️ images, ¶ paragraphs, headings, quotes, lists, code blocks, and horizontal rules.
• 🛠 Flexible: Render whatever you want, from HTML to JSX.

Who is this library for?

If you're working on a project that requires rendering Markdown for short texts like titles, subtitles, and descriptions, but you don't need a full-featured Markdown parser, this library is for you.

Installation

We recommend using NPM to install the package:

npm install @croct/md-lite

Alternatively, you can use Yarn:

yarn add @croct/md-lite

Basic usage

The following sections show how to parse and render Markdown using this library.

Parsing Markdown

To parse a Markdown string into an AST, use the parse function:

import {parse} from '@croct/md-lite';

const markdown = '**Hello**, [World](https://example.com)';

const ast = parse(markdown);

The parse function returns a tree-like structure called an Abstract Syntax Tree (AST). You can find the full AST definition here. Each node's source is the exact text of the input it was parsed from, markers included. Nodes nested deeper than 100 levels are read as text, so that no input can exhaust the stack.

Parsing blocks

By default, the parser reads only inline formatting and paragraphs, which suits short texts, like titles. To also read blocks, as CommonMark does, turn on the blocks option:

import {parse} from '@croct/md-lite';

const ast = parse('# Title\n\n- One\n- Two', {blocks: true});

These are the blocks it reads:

• Headings, from # Heading to ###### Heading, or a paragraph underlined with === or ---
• Quotes, with each line starting with >
• Lists, with items starting with -, *, or +, or with a number followed by . or ), nested by indentation, and with as many paragraphs per item as needed
• Code blocks, fenced by three or more backticks or tildes, with an optional language
• Horizontal rules, like ---, ***, or ___

A list is tight unless a blank line sets its items apart, or the blocks of an item. The text of the items of a tight list is not wrapped in paragraphs, so that it renders as a compact list, while every block in a loose list is.

Rendering Markdown

To render an AST into whatever you want, use the render function. It accepts as input either a Markdown string or an AST:

import {render} from '@croct/md-lite';

// Passing a string as input is equivalent to calling `parse` first
const markdown = '**Hello**, [World](https://example.com)';

const html = render(markdown, {
    fragment: node => node.children.join(''),
    text: node => node.content,
    bold: node => `<b>${node.children}</b>`,
    italic: node => `<i>${node.children}</i>`,
    strike: node => `<s>${node.children}</s>`,
    code: node => `<code>${node.content}</code>`,
    link: node => `<a href="${node.href}">${node.children}</a>`,
    image: node => `<img src="${node.src}" alt="${node.alt}">`,
    paragraph: node => `<p>${node.children.join('')}</p>`,
    heading: node => `<h${node.level}>${node.children}</h${node.level}>`,
    quote: node => `<blockquote>${node.children.join('')}</blockquote>`,
    orderedList: node => `<ol start="${node.start}">${node.items.join('')}</ol>`,
    unorderedList: node => `<ul>${node.items.join('')}</ul>`,
    listItem: node => `<li>${node.children.join('')}</li>`,
    codeBlock: node => `<pre><code>${node.content}</code></pre>`,
    rule: () => '<hr>',
});

Here is an example of how to render the Markdown string above into JSX:

import {render} from '@croct/md-lite';

// Passing a string as input is equivalent to calling `parse` first
const markdown = '**Hello**, [World](https://example.com)';

const jsx = render(markdown, {
    fragment: node => node.children,
    text: node => node.content,
    bold: node => <b key={node.index}>{node.children}</b>,
    italic: node => <i key={node.index}>{node.children}</i>,
    strike: node => <s key={node.index}>{node.children}</s>,
    code: node => <code key={node.index}>{node.content}</code>,
    link: node => <a key={node.index} href={node.href}>{node.children}</a>,
    image: node => <img key={node.index} src={node.src} alt={node.alt} />,
    paragraph: node => <p key={node.index}>{node.children}</p>,
    heading: node => {
        const Heading = `h${node.level}` as const;

        return <Heading key={node.index}>{node.children}</Heading>;
    },
    quote: node => <blockquote key={node.index}>{node.children}</blockquote>,
    orderedList: node => <ol key={node.index} start={node.start}>{node.items}</ol>,
    unorderedList: node => <ul key={node.index}>{node.items}</ul>,
    listItem: node => <li key={node.index}>{node.children}</li>,
    codeBlock: node => <pre key={node.index}><code>{node.content}</code></pre>,
    rule: node => <hr key={node.index} />,
});

Handling unsupported features

In some cases, you might want to intentionally omit certain features from your rendered Markdown. For instance, if your platform doesn't support image rendering, ou can simply return the original source text instead of trying to display the image.

import {render, unescape} from '@croct/md-lite';

render(markdown, {
    // ... other render functions
    image: node => unescape(node.source),
});

This code snippet will simply return the raw source code of the image node instead of trying to render it as an image. You can adapt this approach to handle any other unsupported feature by defining appropriate render functions and accessing the relevant data from the AST.

To render blocks from a string, pass the same option to render, like render(markdown, renderer, {blocks: true}). The render functions for blocks are optional. A block without one, like a list when unorderedList is not given, is rendered as a paragraph of its source text, with its inline formatting, as it would be if blocks were not parsed.

Contributing

Contributions to the package are always welcome!

• Report any bugs or issues on the issue tracker.
• For major changes, please open an issue first to discuss what you would like to change.
• Please make sure to update tests as appropriate.

Testing

Before running the test suites, the development dependencies must be installed:

npm install

Then, to run all tests:

npm run test

Run the following command to check the code against the style guide:

npm run lint

Building

Before building the project, the dependencies must be installed:

npm install

Then, to build the project:

npm run build

License

Copyright © 2015-2023 Croct Limited, All Rights Reserved.

All information contained herein is, and remains the property of Croct Limited. The intellectual, design and technical concepts contained herein are proprietary to Croct Limited s and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Croct Limited.