Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/binarymuse/node-cmark-gfm

Node.js bindings to GitHub's GFM-enhanced fork of cmark, the CommonMark reference implementation in C
https://github.com/binarymuse/node-cmark-gfm

Last synced: 5 days ago
JSON representation

Node.js bindings to GitHub's GFM-enhanced fork of cmark, the CommonMark reference implementation in C

Awesome Lists containing this project

README 

        
# cmark-gfm



cmark-gfm is a Node.js wrapper around [libcmark-gfm](https://github.com/github/cmark-gfm), GitHub's [GFM-enhanced](https://github.github.com/gfm/) fork of [cmark](https://github.com/commonmark/cmark), the reference implementation of [CommonMark](http://commonmark.org/) in C by John MacFarlane.



## Installation



cmark-gfm is distributed via the npm registry, and can be installed with `npm` and similar tools:



```

npm install cmark-gfm

```



## API



**`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 HTML

  * `options` - a hash of options (see *Options*, below)

  * `callback` - a Node.js-style callback to call with the resulting HTML once the Markdown has been rendered

    * `error` - any error that occurred

    * `html` - 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 HTML

  * `options` - 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](https://nodejs.org/api/stream.html) 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'))

```



### Options



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](https://github.github.com/gfm/#disallowed-raw-html-extension-), causing them to have no effect |

| `"autolink"` | Automatically generates links from URLs |

| `"tasklist"` | Renders [GitHub-style task lists](https://help.github.com/articles/about-task-lists/)



## Features



### `sourcepos`



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 code



console.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 code



console.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).



### `hardbreaks`



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


```



### `nobreaks`



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


```



### `githubPreLang`



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!')





```



### `footnotes`



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.



  
    

        
  1. 

          
    You can tell because of all the text ↩
    

        
    2. 

        
  2. 

          
    Just a little bit ↩
    

        
    3. 

      



```



### `fullInfoString`



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')





```



### `unsafe`



By default, `libcmark-gfm` escapes raw HTML and unsafe links:



````markdown

![img](data:image/gif;base64,abccdefgh)



hello!



[link](javascript:alert('omg'))

````



would result in:



```html

img



link


```



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



```html

img


hello!


link


```



If you use the `unsafe` option, you should be sure to do your own sanitization of the resulting HTML.



## Extensions



### `"table"`



The `table` extension allows the parsing and rendering of tables:



```markdown

|Header|

|------|

|Hello |

```



```html



  

    

      Header

    

  

  

    

      Hello

    

  



```



See [the table documentation in the GFM docs](https://github.github.com/gfm/#tables-extension-) for more information.



### `"strikethrough"`



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.



### `"tagfilter"`



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](https://github.github.com/gfm/#disallowed-raw-html-extension-) for more information and the list of filtered tags.



### `"autolink"`



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](https://github.github.com/gfm/#autolinks-extension-) for more information about how libcmark-gfm scans for links.



### `"tasklist"`



The `tasklist` extension enables the rendering of [GitHub-style task lists](https://help.github.com/articles/about-task-lists/).



```markdown

- [ ] Task 1

- [x] Task 2

```



```html

    

      
  •  Task 1
    • 

      
  •  Task 2
    • 



```



See [the task list documentation in the GFM docs](https://github.github.com/gfm/#task-list-items-extension-) for more information about how libcmark-gfm processes task lists.