blueprint-markdown-renderer's Introduction

Blueprint Markdown Renderer

Default parser and set of settings for parsing and rendering of Markdown blocks in API Description Documents.

Installation

$ npm install blueprint-markdown-renderer

Usage

Basic Rendering

import { renderHtml } from 'blueprint-markdown-renderer';

const mdText = '# Heading';

const html = renderHtml(mdText);

console.log("Rendered HTML: ", html);

Advanced Usage

Note that if you alter renderer's settings, you are potentially diverging from the ecosystem, therefore this is not encouraged. However, it's still better to share the same rendering core with customised behaviour than it is to start for the blank slate.

Blueprint Markdown Renderer uses markdown-it under the hood. See markdown-it API Documentation to find all available options how to change renderer.

import { renderHtml, rendererFactory, sanitize } from 'blueprint-markdown-render';
import emojiPlugin from 'markdown-it-emoji';

const renderer = rendererFactory();

// alter default options
renderer.set({ langPrefix: 'lang-', breaks: true });

// add own plugin
renderer.use(emojiPlugin);

const mdText = ':smiley:';

const html = renderHtml(mdText, {
  renderer, // custom renderer
  env, // additional data from parsed input (references, for example)
  sanitize, // run HTML sanitization function
});

console.log("Rendered HTML: ", html);

Motivation

While API Blueprint syntax is based on Markdown, it doesn't care about the (Markdown) content of description blocks. The reference parser actually preserves the source Markdown in the produced API Elements. Same logic applies to

This library is intended to provide a consistent API for parsing those Markdown blocks. Use it to get the same defaults and consistent rendering with the rest of JavaScript API Blueprint ecosystem.

To get consistent experience accross languages, this library uses CommonMark implementation under its hood. Following extensions to default rendering is enabled by default: