@btnguyen2k/mdr

mdr

Render Markdown to HTML with rich extensions.

⭐ Based on markedjs with GFM flavor. Enabled extensions:

• marked-base-url
• marked-mangle
• GFM header-id

⭐ Code highlight with highlight.js.

⭐ Support Katex math formula.

Installation

with npm

$ npm install -S @btnguyen2k/mdr

Usage

This package exports a function mdr that can be used to render Markdown to HTML:

import {mdr} from '@btnguyen2k/mdr'

const markdown = '# Hello World!'
const options = {} // optional
console.log(mdr(markdown, options)) // <h1 id="hello-world">Hello World!</h1>

Options

Function mdr takes an optional 2nd argument, which is an object with the following properties:

Property	Type	Default	Description
inline	boolean	false	If true, the output HTML will not be wrapped in <p> tag.
safety	boolean	true	If true, the output HTML will be sanitized using DOMPurify.
safety_opts	object	(see bellow)	Options for DOMPurify if safety=true.
safety_opts.add_tags	array	['iframe']	Additional tags to allow [1].
safety_opts.add_data_uri_tags	array	['iframe']	Additional tags to allow data URI [1].
safety_opts.add_attrs	array	['target', 'allow']	Additional attributes to allow [1][2].
toc_container	array	undefined	If supplied, the generated table of content will be pushed to this array.
katex	boolean	true	If true, KaTeX support is enabled.
katex_opts	object	{output: 'htmlAndMathml', throwOnError: false}	Options for KaTeX if katex=true. See see https://katex.org/docs/options.html
ghgist	boolean	true	If true, GitHub Gist support is enabled.
ghgist_opts	object	{}	Options for GitHub Gist if ghgist=true. See below for details.
video	boolean	true	If true, video embedding is enabled.
video_opts	object	{}	Options for video embedding if video=true. See below for details.
code_handlers	object	{}	Custom code block handlers, in format {code_id: handler}. If matched, the code enclosed between code_id and will be handled by the specified handler. See below for details.
baseUrl (*)	string	undefined	If supplied, marked-base-url extension is enabled.
headerIds (*)	boolean	true	If true, headings are generated with id attribute.
headerPrefix (*)	string	''	If present, values of generated id attributes are prefixed by this value (imply headingIds=true).
mangle (*)	boolean	true	If true, marked-mangle extension is enabled.
highlight (*)	function	undefined	If supplied, highlight function is used to highlight source code.
langPrefix (*)	string	null	If present, langPrefix is used to prefix language name in generated code block.

• [1] iframe is used by GitHub Gist and Youtube video extensions. allow attribute is also used to enable Youtube features such as fullscreen, autoplay, picture-in-picture, etc.
• [2] target attribute is useful for extrernal links.
• (*) Do use these options with mdr, do not use marked's extensions (e.g. marked-highlight, etc) directly.

Embedding GitHub Gist

mdr supports embedding GitHub Gist in Markdown using the following syntax:

```gh-gist gistUrl [options]
```

Parameters/Options	Description
gistUrl	The GitHub Gist to embed, can be in short form (e.g. btnguyen2k/d7577db0981cb157ae95b67b9f6dd733) or full URL (e.g. https://gist.github.com/btnguyen2k/d7577db0981cb157ae95b67b9f6dd733).
style="custom-css-style"	Custom CSS style to apply to the embedded Gist.
class="custom-css-class"	Custom CSS class to apply to the embedded Gist.

Example:

```gh-gist btnguyen2k/d7577db0981cb157ae95b67b9f6dd733 class="gist-embed" style="width: 100%; padding-bottom: 8px;"
```

Default values for options style and class can be specified in ghgist_opts:

import {mdr} from '@btnguyen2k/mdr'

const input = '```gh-gist btnguyen2k/d7577db0981cb157ae95b67b9f6dd733\n```'
const output = mdr(input, {
  ghgist_opts: {
    style: 'width: 100%; padding-bottom: 8px;',
    class: 'gist-embed'
  }
})

Embedding video

mdr supports embedding video in Markdown using the following syntax:

```video videoUrl [options]
```

Parameters/Options	Description
videoUrl	The video embed.
style="custom-css-style"	Custom CSS style to apply to the embedded video.
class="custom-css-class"	Custom CSS class to apply to the embedded video.

Example:

```video my-video.mp4 class="video-embed" style="width: 100%; padding-bottom: 8px;"
```

Default values for options style and class can be specified in video_opts:

import {mdr} from '@btnguyen2k/mdr'

const input = '```video my-video.mp4\n```'
const output = mdr(input, {
  video_opts: {
    style: 'width: 100%; padding-bottom: 8px;',
    class: 'gist-embed'
  }
})

Extending MDR

Application developers can extend mdr by adding custom code block handlers. For example, the following code adds a custom code block handler to support [Bootstrap Alerts](https://getbootstrap.com/docs/5.0/components/alerts/:

const opts = {
  code_handlers: {
    'bs-alert': (code, infoString) => {
      const alertStyle = infoString ? infoString.slice('bs-alert'.length).trim() : 'primary'
      return `<div class="alert alert-${alertStyle}" role="alert">${code}</div>`
    }
  }
}

const input = '```bs-alert info\nA simple primary alert—check it out!\n```'
const output = mdr(input, opts) // '<div class="alert alert-info" role="alert">A simple primary alert—check it out!</div>'

License

MIT - see LICENSE.md.