Node bindings to GitHub's GFM-enhanced fork of the cmark Markdown parser
npm install cmark-gfmcmark-gfm is a Node.js wrapper around libcmark-gfm, GitHub's GFM-enhanced fork of cmark, the reference implementation of CommonMark in C by John MacFarlane.
cmark-gfm is distributed via the npm registry, and can be installed with npm and similar tools:
```
npm install cmark-gfm
renderHtml(markdown[, options][, callback])
Converts a Markdown string to HTML asynchronously. If you do not provide a callback, renderHtml will return a Promise that will resolve to the resulting HTML. If options is omitted, default options will be used.
* markdown - a string of Markdown to convert to HTMLoptions
- a hash of options (see Options*, below)callback
* - a Node.js-style callback to call with the resulting HTML once the Markdown has been renderederror
* - any error that occurredhtml
* - the resulting HTML
Example:
`javascript
const cmark = require('cmark-gfm')
const options = { ... }
// Promise-style
cmark.renderHtml('# Hello there!', options)
.then(html => console.log(html))
.catch(error => console.error(error))
// Callback-style
cmark.renderHtml('# Hello there!', options, (error, html) => {
if (error) {
console.error(error)
return
}
console.log(html)
})
`
html = renderHtmlSync(markdown[, options])
Converts a Markdown string to HTML synchronously. If options is omitted, default options will be used.
* markdown - a string of Markdown to convert to HTMLoptions
- a hash of options (see Options*, below)
Example:
`javascript
const cmark = require('cmark-gfm')
const options = { ... }
try {
const html = cmark.renderHtmlSync('# Hello there!', options)
console.log(html)
} catch (error) {
console.error(error)
}
`
createStreamingParser([options])
Creates a stream with a writable end that accepts Markdown and a readable end that produces HTML. The parser ingests Markdown and converts it to HTML asynchronously. If options is omitted, default options will be used.
options - a hash of options (see Options*, below)
Example:
`javascript
const cmark = require('cmark-gfm')
const fs = require('fs')
const options = { ... }
fs.createReadStream('./input.md')
.pipe(cmark.createStreamingParser(options))
.pipe(fs.createWriteStream('./output.html'))
`
cmark-gfm supports a variety of options that it passes to the underlying libcmark-gfm library. You can enable most options by setting its name to the value of true in your options object; to enable an extension, add its name as a key to an extensions object with a value of true. For example, to enable the smart and footnotes options and the strikethrough extension:
`javascript
const cmark = require('cmark-gfm')
const options = {
smart: true,
footnotes: true,
extensions: {
strikethrough: true
}
}
cmark.renderHtml(markdown, options)
.then(/ ... /)
`
You can find a summary of all the options in the table below, as well as additional information for some options in the Features section later in this document.
| Name | Type | Description
|---|---|---|
| sourcepos* | bool | Adds a data-sourcepos attribute to elements that indicate the range of Markdown that resulted in the element |hardbreaks
| * | bool | Renders softbreak elements as hard line breaks |nobreaks
| * | bool | Renders softbreak elements as spaces |validateUtf8
| | bool | Replaces illegal UTF-8 sequences with U+FFFD |smart
| | bool | Replaces straight quotes with curly ones, and turns --- into em dashes and -- into en dashes |githubPreLang
| * | bool | Uses GitHub style
tags for code blocks |
| liberalHtmltag | bool | Allows HTML tags to be parsed as HTML even if they are not well formed (e.g. < div> instead of just ) |
| footnotes* | bool | Enables footnote parsing and rendering |
| strikethroughDoubleTilde | bool | When enabled, the strikethrough extension will only render text as strikethrough if it is surrounded by exactly ~~two tildes~~ |
| fullInfoString* | bool | Adds additional code block info as an additional attribute on the resulting HTML element |
| unsafe* | bool | Allows raw HTML and unsafe links (javascript:, vbscript:, file:, and data: except for image/png, image/gif, image/jpeg, or image/webp mime types). Otherwise, raw HTML is replaced by a placeholder HTML comment, and unsafe links are replaced with empty strings. |
| extensions* | object | Which extensions to enable |
| \ more information in the Features and Extensions sections below* |libcmark-gfm also exposes several Markdown extensions that you can enable by passing their name as keys to the
extensions option (with a value of true). You can find a summary of all the extensions in the table below, as well as additional information in the Extensions section later in this document.| Name | Description |
|---|---|
|
"table" | Renders tables |
| "strikethrough" | Renders text as strikethrough when surrounded by ~tildes~ |
| "tagfilter" | Escapes certain dangerous HTML tags, causing them to have no effect |
| "autolink" | Automatically generates links from URLs |
| "tasklist" | Renders GitHub-style task listsFeatures
$3
Enabling the
sourcepos option adds a data-sourcepos attribute to block level elements which indicate the row and column positions from the original Markdown source that resulted in that HTML element. For example, given the markdown:``markdown
Hello!
Hi there. This is a Markdown file. You probably knew that already.
`javascript
// Here's a bit of JS codeconsole.log('hello')
`And a short list:
* One
* Two
* Three
``Rendering with the
sourcepos attribute would result in output similar to:`html
Hello!
Hi there. This is a Markdown file. You probably knew that already.
// Here's a bit of JS codeconsole.log('hello')
And a short list:
- One
- Two
- Three
`You can see, for example, that the
tag that represents the code block was generated from the Markdown text between row 5 column 1 and row 9 column 3 (inclusive and 1-indexed).$3
Enabling the
hardbreaks option renders "softbreak" elements as hard line breaks.`markdown
abc
def
`would normally result in
`html
abc\ndef
`but with
hardbreaks enabled, it results in`html
abc
\ndef
`$3
Enabling the
nobreaks option renders "softbreak" elements as spaces:`markdown
abc
def
`would normally result in
`html
abc\ndef
`but with
nobreaks enabled, it results in`html
abc def
`$3
Normally, code blocks like the following:
``markdown
`javascript
console.log('hello!')
`
``would result in HTML like this:
`html
console.log('hello!')
`With
githubPreLang enabled, it would instead result in the following HTML:`html
console.log('hello!')
`$3
Enabling the
footnotes option turns on the parsing and rendering of footnotes. Here's a simple example:``markdown
Here is some text[^1]. Here's a little bit more[^more].[^1]: You can tell because of all the text
[^more]: Just a little bit
``And the resulting HTML:
`html
Here is some text1. Here's a little bit more2.
`$3
When the
fullInfoString feature is enabled, extra text after the language tag for a code block (which is normally discarded) is included in a data-meta attribute on the resulting HTML element:``markdown
`javascript here is some more text
console.log('hi')
`
```html
console.log('hi')
`$3
By default,
libcmark-gfm escapes raw HTML and unsafe links:
``markdown
!imghello!link)
``would result in:
`html

`Notice that the
div and the javascript:alert link have been sanitized. With the unsafe option enabled, the resulting HTML would be:`html

hello!
`If you use the
unsafe option, you should be sure to do your own sanitization of the resulting HTML.Extensions
$3
The
table extension allows the parsing and rendering of tables:`markdown
|Header|
|------|
|Hello |
``html
Header
Hello
`See the table documentation in the GFM docs for more information.
$3
The
strikethrough extension renders text surrounded by ~one~ or ~~two~~ tildes as strikethrough using the tag. If the strikethroughDoubleTilde option is enabled, text will only be rendered as strikethrough if it is surrounded by exactly ~~two~~ tildes.$3
Certain HTML tags can be particularly troublesome as they change how HTML is interpreted in a way unique to them. The
tagfilter extension escapes these tags by replacing the leading < with <. The following markdown:`markdown
What a weird tag
`would result in this HTML:
`html
What a weird <xmp> tag
`See the Disallowed Raw HTML documentation in the GFM docs for more information and the list of filtered tags.
$3
The
autolink extension recognizes URLs in text and automatically turns them into links:`markdown
Visit us at https://github.com!
``html
Visit us at https://github.com!
`See the autolinks documentation in the GFM docs for more information about how libcmark-gfm scans for links.
$3
The
tasklist extension enables the rendering of GitHub-style task lists.`markdown
- [ ] Task 1
- [x] Task 2
``html
- Task 1
- Task 2
``See the task list documentation in the GFM docs for more information about how libcmark-gfm processes task lists.