cmark-gfm-js


* A port of GitHub's cmark to JavaScript (using Emscripten)
* Support Node.js and browser
* GitHub Flavored Markdown (GFM) Compatibility
* HTML Sanitization
* Benchmarks
* TypeScript friendly

Installation

$3

``sh
yarn add cmark-gfm-js
`

$3

Download cmark-gfm.js

Usage

`typescript
/**
* convert converts a GitHub Flavored Markdown (GFM) string to HTML.
*/
function convert(markdown: string, options?: number): string;

/**
* convertUnsafe calls convert with GFM's tagfilter extension disabled. (See "HTML Sanitization" below for details)
*/
function convertUnsafe(markdown: string, options?: number): string;
`

Examples


In Node.js:
`js
const gfm = require('cmark-gfm-js');

const markdown = '# Hi\nThis ~text~~~~ is ~~~~curious 😡🙉🙈~.';
let html = gfm.convert(markdown);
console.log(html);
/** Prints:

Hi

This text is curious 😡🙉🙈.

*/

// Specify an option
html = gfm.convert(markdown, gfm.Option.sourcePos);
console.log(html);
/** Prints

Hi

This text is curious 😡🙉🙈.

*/
`

In browser:
`html


---

`

GFM Compatibility

Task list items are not supported (issue). Use emojis instead. e.g.
`
✅ Done.
❌ To be done.
`

HTML Sanitization

$3

> TL;DR: See A Good HTML Sanitizer for a working example of a HTML Sanitizer.

The current CommonMark Spec 0.27 allows raw HTML tags in markdown but does not state anything on sanitizing raw HTML data. cmark-gfm comes with two possible (but not perfect) builtin solutions.

* cmark comes with a SAFE option, which will suppress most raw HTML tags (see Options below). Drawback: many safe tags are killed, not configurable.
* cmark-gfm comes with an extension called tagfilter, which filters a set of HTML tags, and is written in GFM Spec. (see spec). Drawbacks: cannot filter tags with malicious attributes, not configurable.

Let's see a real example:
`js
const gfm = require('cmark-gfm-js');

/** Consider the following markdown
❌
❌
✅
✅

*/
const dangerous = '\n\n\n';

// GFM's tagfilter is enabled by default.
const tagfiltered = gfm.convert(dangerous);
console.log(tagfiltered);
/** Prints
<script>alert(1)</script>

*/

// Do not use GFM's tagfilter, use cmark's SAFE option.
// gfm.convertUnsafe will disable GFM's tagfilter extension.
const cmarkSafe = gfm.convertUnsafe(dangerous, gfm.Option.safe);
console.log(cmarkSafe);
/** Prints


*/
`

So actually none of the above solutions work perfectly. GFM's tag filter is not able to filter some tags with malicious attributes, while cmark's SAFE option seems like an overkill.

$3


If you want to sanitize HTML in a good way, I suggest you completely ignore the builtin solutions above from cmark-gfm, instead output raw HTML with gfm.convertUnsafe and use a more professional HTML sanitizer instead. For example ting:
`js
const gfm = require('cmark-gfm-js');
const ting = require('ting');

/** Dangerous markdown
❌
❌
✅
✅

*/
const dangerous = '\n\n\n';

const unsafeHTML = gfm.convertUnsafe(dangerous);
const safeHTML = ting.sanitize(unsafeHTML);

console.log(Unsafe:\n${unsafeHTML}\nSafe: ${safeHTML});
/** Prints
Unsafe:





Safe:





*/
`

See examples/sanitizeHTML for full source code.

cmark-gfm Options


`typescript
enum Option {
/**
* ### Options affecting rendering
*/

/* Include a data-sourcepos attribute on all block elements. /
sourcePos = (1 << 1),

/** Render softbreak elements as hard line breaks.
*/
softBreak = (1 << 2),

/** Suppress raw HTML and unsafe links (javascript:, vbscript:,
* file:, and data:, except for image/png, image/gif,
* image/jpeg, or image/webp mime types). Raw HTML is replaced
* by a placeholder HTML comment. Unsafe links are replaced by
* empty strings.
*/
safe = (1 << 3),

/** Render softbreak elements as spaces.
*/
noBreaks = (1 << 4),

/**
* ### Options affecting parsing
*/

/** Legacy option (no effect).
*/
normalize = (1 << 8),

/** Validate UTF-8 in the input before parsing, replacing illegal
* sequences with the replacement character U+FFFD.
*/
validateUTF8 = (1 << 9),

/** Convert straight quotes to curly, --- to em dashes, -- to en dashes.
*/
smart = (1 << 10),

/** Use GitHub-style

 tags for code blocks instead of 
   * class="language-x">.
   */
  githubPreLang = (1 << 11),
  /** Be liberal in interpreting inline HTML tags.
   */
  liberalHTMLTag = (1 << 12),
  /** Parse footnotes.
   */
  footnotes = (1 << 13),
  /** Only parse strikethroughs if surrounded by exactly 2 tildes.
   * Gives some compatibility with redcarpet.
   */
  strikethroughDoubleTilde = (1 << 14),
  /** Use style attributes to align table cells instead of align attributes.
   */
  tablePreferStyleAttributes = (1 << 15),
  
  /** tablePreferStyleAttributes.
   */
  default = tablePreferStyleAttributes,
}
``
Who is using cmark-gfm-js

Coldfunction is using cmark-gfm-js to generate HTML from markdown in browser, and uses cmark-gfm in its backend services.