@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, about 1.5 KB gzipped.
• 🌐 Cross-environment: Works in Node.js and browsers.
• ✍️ Minimalist: Supports only italic, bold, strikethrough, inline code, links, 🖼️ images, and ¶ paragraphs.
• 🛠 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.

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, {
    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>`,
    fragment: node => node.children.join(''),
});

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, {
    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>,
    fragment: node => node.children.map(child => <Fragment key={child.index}>{child}</Fragment>),
});

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.

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.