Epic-remark NPM

`epic-remark`

epic-remark is a Markdown to HTML processor built on top of remark. It adds GitHub-flavoured markdown capabilities, alongside some handy must-have custom plugins.

Use the all-in-one processMarkdown function to format your markdown into HTML, or import the custom plugins working behind the scenes one-by-one to mix your own flavour of Markdown HTML.

npm bundle size GitHub Workflow Status (with event) GitHub issues GitHub pull requests npm npm NPM

Currently supported frameworks:

Next.js
Nuxt.js

All supported frameworks are available in the examples/ directory. You can still use epic-remark with other frameworks, but you'll need to sort out the build and integration yourself.

Dependencies

remark: ^15.0.1
remark-gfm: ^4.0.0
remark-html: ^16.0.1
rehype-stringify: ^10.0.0
remark-rehype: ^11.0.0
rehype-raw: ^7.0.0

How it works

epic-remark first uses remark and remark-html to convert your initial markdown to HTML. Then, remark-gfm is applied to enable the use of GitHub-flavoured markdown (tables, strikethrough, etc). At this point, the HTML is in a special remark AST (Abstract Syntax Tree). While it is possible to traverse and modify the tree, it can have some unexpected results. To create a more predictable environment, epic-remark uses remark-rehype to convert the remark AST to an easily adjustable HAST (HTML Abstract Syntax Tree).

epic-remark then runs any of the custom epic-remark plugins you've enabled, serializes the newly modified HAST using rehype-stringify, and returns the HTML content back to you, ready to display on your frontend.

Getting started

Installation

Install epic-remark using npm:

npm install epic-remark

or with yarn

yarn add epic-remark

Usage

To use epic-remark in your project, you can import the processMarkdown function and use it to convert Markdown into HTML.

import { processMarkdown } from 'epic-remark';

const markdown = `# Your Markdown Here`;
const html = processMarkdown(markdown);

Configuration

processMarkdown accepts an optional options object, which allows you to configure various aspects of the Markdown processing.

Basic Options

addHeadingIds: Boolean. Automatically adds IDs to heading tags (h1 to h6). Defaults to false.
wrapConfig: Object. Defines custom wrappers for specified HTML elements. Defaults to { img: 'epic-remark-image', table: 'epic-remark-table' }.
addTableOfContents: Boolean. Generates a table of contents based on headings. Defaults to false.
calculateReadingTime: Boolean. Estimates the reading time of the content. Defaults to false.
wordsPerMinute: Number. Defines the words-per-minute metric used to calculate reading time. Defaults to 250.
renderEmbeds: Boolean. Embeds content from external sources like YouTube videos or GitHub gists. Defaults to false.

Example with Options

import { processMarkdown } from 'epic-remark';

const markdown = `# Your Markdown Here`;

const options = {
    addHeadingIds: true,
    wrapConfig: { img: 'custom-img-class' },
    addTableOfContents: true,
    calculateReadingTime: true,
    wordsPerMinute: 200,
    renderEmbeds: true
};

const html = processMarkdown(markdown, options);

See the documentation for more details on each option.

Plugins

`processMarkdown`

The processMarkdown function is the core of epic-remark. It converts markdown to HTML, applying a range of configurable options to enable additional plugins during execution. It is the primary function you'll use, with other plugins augmenting its capabilities.

`addHeadingIds`

Automatically adds an id attribute to all headings (h1 to h6). The id value mirrors the heading's text, transformed into a URL-friendly format. This plugin is ideal for creating anchor links and improving navigability within documents.

`wrapElements`

Provides the ability to wrap specified HTML elements in a div with a customizable class. By default, img and table tags are wrapped in divs with classes epic-remark-image and epic-remark-table, respectively. Users can extend or override these defaults using the wrapConfig option in processMarkdown, allowing for more granular control over the styling and layout of elements.

`addTableOfContents`

Generates a table of contents based on the document's headings. Users can configure this plugin to either prepend the table of contents directly into the content or return it as a separate HTML string. This plugin enhances document structure and user navigation.

`calculateReadingTime`

Estimates the reading time of the provided markdown content. The calculation is based on a standard words-per-minute metric, which can be adjusted via options. The reading time is returned in minutes, offering a quick overview of the content length.