marked-ts

marked-ts

A full-featured markdown parser and compiler, written in TypeScript.

This is fork of popular library marked from this commit (Merge pull request #961 from chjj/release-0.3.7, Dec 1, 2017).

For now - work in progress (there is only alpha.4 version).

Install

If you want to use marked-ts without TypeScript functionality, you can install it with --no-optional switch:

npm install marked-ts --no-optional --save

Usage

Minimal usage:

import { Marked } from 'marked-ts';

console.log(Marked.parse('I am using __markdown__.'));
// Outputs: I am using <strong>markdown</strong>.

Example setting options with default values:

import { Marked, Renderer } from 'marked-ts';

Marked.setOptions
({
  renderer: new Renderer,
  gfm: true,
  tables: true,
  breaks: false,
  pedantic: false,
  sanitize: false,
  smartLists: true,
  smartypants: false
});

console.log(Marked.parse('I am using __markdown__.'));

API

Methods of Marked class and necessary types

/**
 * Accepts Markdown text and returns text in HTML format.
 * 
 * @param src String of markdown source to be compiled.
 * 
 * @param options Hash of options. Can also be
 * set using the `Marked.setOptions` method as seen above.
 * 
 * @param callback Function called when the `src`
 * has been fully parsed when using async call. If
 * the `options` argument is omitted, this can be used as
 * the second argument.
 */
static parse(src: string): string;
static parse(src: string, options: MarkedOptions): string;
static parse(src: string, callback: ParseCallback): any;
static parse(src: string, options: MarkedOptions, callback: ParseCallback): any;


/**
 * Merges the default options with options that will be set.
 * 
 * @param options Hash of options.
 */
static setOptions(options: MarkedOptions): this;

type ParseCallback<T=string> = (err: Error, output?: string) => T;

// This class also using as a type.
class MarkedOptions
{
  gfm?: boolean = true;
  tables?: boolean = true;
  breaks?: boolean = false;
  pedantic?: boolean = false;
  sanitize?: boolean = false;
  sanitizer?: (text: string) => string;
  mangle?: boolean = true;
  smartLists?: boolean = false;
  silent?: boolean = false;
  /**
   * @param code The section of code to pass to the highlighter.
   * @param lang The programming language specified in the code block.
   * @param callback The callback function to call when using an async highlighter.
   */
  highlight?: (code: string, lang: string, callback?: ParseCallback) => any;
  langPrefix?: string = 'lang-';
  smartypants?: boolean = false;
  headerPrefix?: string = '';
  /**
   * An object containing functions to render tokens to HTML. Default: `new Renderer()`
   */
  renderer?: Renderer;
  /**
   * Self-close the tags for void elements (&lt;br/&gt;, &lt;img/&gt;, etc.)
   * with a "/" as required by XHTML.
   */
  xhtml?: boolean = false;
  /**
   * The function that will be using to escape HTML entities.
   * By default using inner helper.
   */
  escape?: (html: string, encode?: boolean) => string = escape;
  /**
   * The function that will be using to unescape HTML entities.
   * By default using inner helper.
   */
  unescape: (html: string) => string = unescape;
}

Example usage with highlight.js

npm install highlight.js @types/highlight.js --save

A function to highlight code blocks:

import { Marked } from 'marked-ts';
import { highlightAuto } from 'highlight.js';

let md = '```js\n console.log("hello"); \n```';

// Using async version of `Marked.parse()`
Marked.parse(md, (err, output) =>
{
  if(err)
    throw err;

  console.log(output);
});

// Synchronous highlighting with highlight.js
Marked.setOptions({ highlight: code => highlightAuto(code).value });

console.log(Marked.parse(md));

Overriding renderer methods

The renderer option allows you to render tokens in a custom manner. Here is an example of overriding the default heading token rendering by adding custom head id:

import { Marked, Renderer, MarkedOptions } from 'marked-ts';

// Setting some options for Marked.
const markedOptions: MarkedOptions = {};

const renderer = new Renderer(markedOptions);

// Overriding renderer.
renderer.heading = function (text, level)
{
  const patt = /\s?{([^}]+)}$/;
  const link = patt.exec(text);
  let linkStr: string;
  
  if(link && link.length && link[1])
  {
    text = text.replace(patt, '');
    linkStr = link[1];
  }
  else
  {
    linkStr = text.toLocaleLowerCase().replace(/[^\wа-яіїє]+/gi, '-');
  }

  return '<h' + level + ' id="' + linkStr + '">' + text + '</h' + level + '>';
};

markedOptions.renderer = renderer;
Marked.setOptions(markedOptions);

console.log(Marked.parse('# heading {my-custom-hash}'));

This code will output the following HTML:

<h1 id="my-custom-hash">heading</h1>

Renderer methods API

//*** Block level renderer methods. ***

code(code: string, lang?: string, escaped?: boolean): string;

blockquote(quote: string): string;

html(html: string): string;

heading(text: string, level: number, raw: string): string;

hr(): string;

list(body: string, ordered?: boolean): string;

listitem(text: string): string;

paragraph(text: string): string;

table(header: string, body: string): string;

tablerow(content: string): string;

tablecell(content: string, flags: {header?: boolean, align?: Align}): string;

//*** Inline level renderer methods. ***

strong(text: string): string;

em(text: string): string;

codespan(text: string): string;

br(): string;

del(text: string): string;

link(href: string, title: string, text: string): string;

image(href: string, title: string, text: string): string;

text(text: string): string;

Philosophy behind marked

The point of marked was to create a markdown compiler where it was possible to frequently parse huge chunks of markdown without having to worry about caching the compiled output somehow...or blocking for an unnecessarily long time.

Marked is very concise and still implements all markdown features.

Marked more or less passes the official markdown test suite in its entirety. This is important because a surprising number of markdown compilers cannot pass more than a few tests. It was very difficult to get marked as compliant as it is.

Along with implementing every markdown feature, marked also implements GFM features.

Benchmarks

node v8.9.x

npm install
npm run compile
npm run bench

By default, these benchmarks run the entire markdown test suite (52 files) once. The test suite includes every feature. It doesn't cater to specific aspects.

engine	completed in ms
marked-ts alpha.4	16
marked v0.3.7	18
markdown v0.5.0	52
remarkable v1.7.1	53
showdown v1.8.5	107
markdown-it v8.4.0	118

Options for benchmarks

-l, --length       Approximate string length in kilobytes. Default ~ 50 KB.
-t, --times        Number of runs this bench. Default - 1 times.
-e, --ext          Extended bench for `marked-ts` and `marked`. Default - false.

For this purpose, test files are used and accumulated in one file. If you specify, for example, --length 100 the first file will be taken, check whether it is longer than 100 kilobytes, and if no - it will be attached to the first one and check its length, and so on.

Example of usage bench options

In order for npm passing the parameters, they need to be separated via --:

npm run bench -- --length 500 --times 1

Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work. </legalese>

License

Copyright (c) 2011-2014, Christopher Jeffrey. (MIT License)

Copyright (c) 2018, Костя Третяк. (MIT License)

See LICENSE for more info.