markdown-it

• • new Core()

• • Core.process(state)

Executes core chain rules.

• • Core#ruler
  • • Ruler

Ruler instance. Keep configuration of core rules.

• • new MarkdownIt([presetName][, options])

• • presetName
  • • String

  • optional, commonmark / zero

• • options
  • • Object

Creates parser instanse with given config. Can be called without new.

presetName

MarkdownIt provides named presets as a convenience to quickly enable/disable active syntax rules and options for common use cases.

• "commonmark" - configures parser to strict CommonMark mode.
• default - similar to GFM, used when no preset name given. Enables all available rules, but still without html, typographer & autolinker.
• "zero" - all rules disabled. Useful to quickly setup your config via .enable(). For example, when you need only bold and italic markup and nothing else.

options:

• html - false. Set true to enable HTML tags in source. Be careful! That's not safe! You may need external sanitizer to protect output from XSS. It's better to extend features via plugins, instead of enabling HTML.
• xhtmlOut - false. Set true to add '/' when closing single tags (<br />). This is needed only for full CommonMark compatibility. In real world you will need HTML output.
• breaks - false. Set true to convert \n in paragraphs into <br>.
• langPrefix - language-. CSS language class prefix for fenced blocks. Can be useful for external highlighters.
• linkify - false. Set true to autoconvert URL-like text to links.
• typographer - false. Set true to enable some language-neutral replacement + quotes beautification (smartquotes).
• quotes - “”‘’, String or Array. Double + single quotes replacement pairs, when typographer enabled and smartquotes on. For example, you can use '«»„“' for Russian, '„“‚‘' for German, and ['«\xA0', '\xA0»', '‹\xA0', '\xA0›'] for French (including nbsp).
• highlight - null. Highlighter function for fenced code blocks. Highlighter function (str, lang) should return escaped HTML. It can also return empty string if the source was not changed and should be escaped externaly. If result starts with <pre... internal wrapper is skipped.

Example

// commonmark mode
var md = require('markdown-it')('commonmark');

// default mode
var md = require('markdown-it')();

// enable everything
var md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: true
});

Syntax highlighting

var hljs = require('highlight.js') // https://highlightjs.org/

var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return hljs.highlight(str, { language: lang, ignoreIllegals: true }).value;
      } catch (__) {}
    }

    return ''; // use external default escaping
  }
});

Or with full wrapper override (if you need assign class to <pre>):

var hljs = require('highlight.js') // https://highlightjs.org/

// Actual default values
var md = require('markdown-it')({
  highlight: function (str, lang) {
    if (lang && hljs.getLanguage(lang)) {
      try {
        return '<pre class="hljs"><code>' +
               hljs.highlight(str, { language: lang, ignoreIllegals: true }).value +
               '</code></pre>';
      } catch (__) {}
    }

    return '<pre class="hljs"><code>' + md.utils.escapeHtml(str) + '</code></pre>';
  }
});

• • MarkdownIt.configure(presets)

Batch load of all options and compenent settings. This is internal method, and you probably will not need it. But if you will - see available presets and data structure here

We strongly recommend to use presets instead of direct config loads. That will give better compatibility with next versions.

• • MarkdownIt.disable(list, ignoreInvalid)

• • list
  • • String
    • Array

  • rule name or list of rule names to disable.

• • ignoreInvalid
  • • Boolean

  • set true to ignore errors when rule not found.

The same as MarkdownIt.enable, but turn specified rules off.

• • MarkdownIt.enable(list, ignoreInvalid)

• • list
  • • String
    • Array

  • rule name or list of rule names to enable

• • ignoreInvalid
  • • Boolean

  • set true to ignore errors when rule not found.

Enable list or rules. It will automatically find appropriate components, containing rules with given names. If rule not found, and ignoreInvalid not set - throws exception.

Example

var md = require('markdown-it')()
            .enable(['sub', 'sup'])
            .disable('smartquotes');

• • MarkdownIt.parse(src, env)
  • • Array

• • src
  • • String

  • source string

• • env
  • • Object

  • environment sandbox

Parse input string and return list of block tokens (special token type "inline" will contain list of inline tokens). You should not call this method directly, until you write custom renderer (for example, to produce AST).

env is used to pass data between "distributed" rules and return additional metadata like reference info, needed for the renderer. It also can be used to inject data in specific cases. Usually, you will be ok to pass {}, and then pass updated object to renderer.

• • MarkdownIt.parseInline(src, env)
  • • Array

• • src
  • • String

  • source string

• • env
  • • Object

  • environment sandbox

The same as MarkdownIt.parse but skip all block rules. It returns the block tokens list with the single inline element, containing parsed inline tokens in children property. Also updates env object.

• • MarkdownIt.render(src[, env])
  • • String

• • src
  • • String

  • source string

• • env
  • • Object

  • environment sandbox

Render markdown string into html. It does all magic for you :).

env can be used to inject additional metadata ({} by default). But you will not need it with high probability. See also comment in MarkdownIt.parse.

• • MarkdownIt.renderInline(src[, env])
  • • String

• • src
  • • String

  • source string

• • env
  • • Object

  • environment sandbox

Similar to MarkdownIt.render but for single paragraph content. Result will NOT be wrapped into <p> tags.

• • MarkdownIt.set(options)

Set parser options (in the same format as in constructor). Probably, you will never need it, but you can change options after constructor call.

Example

var md = require('markdown-it')()
            .set({ html: true, breaks: true })
            .set({ typographer, true });

Note: To achieve the best possible performance, don't modify a markdown-it instance options on the fly. If you need multiple configurations it's best to create multiple instances and initialize each with separate config.

• • MarkdownIt.use(plugin, params)

Load specified plugin with given params into current parser instance. It's just a sugar to call plugin(md, params) with curring.

Example

var iterator = require('markdown-it-for-inline');
var md = require('markdown-it')()
            .use(iterator, 'foo_replace', 'text', function (tokens, idx) {
              tokens[idx].content = tokens[idx].content.replace(/foo/g, 'bar');
            });

• • MarkdownIt#normalizeLink(url)
  • • String

Function used to encode link url to a machine-readable format, which includes url-encoding, punycode, etc.

• • MarkdownIt#normalizeLinkText(url)
  • • String

Function used to decode link url to a human-readable format`

• • MarkdownIt#validateLink(url)
  • • Boolean

Link validation function. CommonMark allows too much in links. By default we disable javascript:, vbscript:, file: schemas, and almost all data:... schemas except some embedded image types.

You can change this behaviour:

var md = require('markdown-it')();
// enable everything
md.validateLink = function () { return true; }

• • MarkdownIt#block
  • • ParserBlock

Instance of ParserBlock. You may need it to add new rules when writing plugins. For simple rules control use MarkdownIt.disable and MarkdownIt.enable.

• • MarkdownIt#core
  • • Core

Instance of Core chain executor. You may need it to add new rules when writing plugins. For simple rules control use MarkdownIt.disable and MarkdownIt.enable.

• • MarkdownIt#helpers
  • • helpers

Link components parser functions, useful to write plugins. See details here.

• • MarkdownIt#inline
  • • ParserInline

Instance of ParserInline. You may need it to add new rules when writing plugins. For simple rules control use MarkdownIt.disable and MarkdownIt.enable.

• • MarkdownIt#linkify
  • • LinkifyIt

linkify-it instance. Used by linkify rule.

• • MarkdownIt#renderer
  • • Renderer

Instance of Renderer. Use it to modify output look. Or to add rendering rules for new token types, generated by plugins.

Example

var md = require('markdown-it')();

function myToken(tokens, idx, options, env, self) {
  //...
  return result;
};

md.renderer.rules['my_token'] = myToken

See Renderer docs and source code.

• • MarkdownIt#utils
  • • utils

Assorted utility functions, useful to write plugins. See details here.

• • new ParserBlock()

• • ParserBlock.parse(str, md, env, outTokens)

Process input string and push block tokens into outTokens

• • ParserBlock#ruler
  • • Ruler

Ruler instance. Keep configuration of block rules.

• • new ParserInline()

• • ParserInline.parse(str, md, env, outTokens)

Process input string and push inline tokens into outTokens

• • ParserInline#ruler
  • • Ruler

Ruler instance. Keep configuration of inline rules.

• • ParserInline#ruler2
  • • Ruler

Ruler instance. Second ruler used for post-processing (e.g. in emphasis-like rules).

• • new Renderer()

Creates new Renderer instance and fill Renderer#rules with defaults.

• • Renderer.render(tokens, options, env)
  • • String

• • tokens
  • • Array

  • list on block tokens to renter

• • options
  • • Object

  • params of parser instance

• • env
  • • Object

  • additional data from parsed input (references, for example)

Takes token stream and generates HTML. Probably, you will never need to call this method directly.

• • Renderer.renderAttrs(token)
  • • String

Render token attributes to string.

• • Renderer.renderInline(tokens, options, env)
  • • String

• • tokens
  • • Array

  • list on block tokens to renter

• • options
  • • Object

  • params of parser instance

• • env
  • • Object

  • additional data from parsed input (references, for example)

The same as Renderer.render, but for single token of inline type.

• • Renderer.renderInlineAsText(tokens, options, env)
  • • String

• • tokens
  • • Array

  • list on block tokens to renter

• • options
  • • Object

  • params of parser instance

• • env
  • • Object

  • additional data from parsed input (references, for example)

Special kludge for image alt attributes to conform CommonMark spec. Don't try to use it! Spec requires to show alt content with stripped markup, instead of simple escaping.

• • Renderer.renderToken(tokens, idx, options)
  • • String

• • tokens
  • • Array

  • list of tokens

• • idx
  • • Numbed

  • token index to render

• • options
  • • Object

  • params of parser instance

Default token renderer. Can be overriden by custom function in Renderer#rules.

• • Renderer#rules
  • • Object

Contains render rules for tokens. Can be updated and extended.

Example

var md = require('markdown-it')();

md.renderer.rules.strong_open  = function () { return '<b>'; };
md.renderer.rules.strong_close = function () { return '</b>'; };

var result = md.renderInline(...);

Each rule is called as independent static function with fixed signature:

function my_token_render(tokens, idx, options, env, renderer) {
  // ...
  return renderedHTML;
}

See source code for more details and examples.

• • new Ruler()

• • Ruler.after(afterName, ruleName, fn[, options])

• • afterName
  • • String

  • new rule will be added after this one.

• • ruleName
  • • String

  • name of added rule.

• • fn
  • • Function

  • rule function.

• • options
  • • Object

  • rule options (not mandatory).

Add new rule to chain after one with given name. See also Ruler.before, Ruler.push.

Options:

• alt - array with names of "alternate" chains.

Example

var md = require('markdown-it')();

md.inline.ruler.after('text', 'my_rule', function replace(state) {
  //...
});

• • Ruler.at(name, fn[, options])

• • name
  • • String

  • rule name to replace.

• • fn
  • • Function

  • new rule function.

• • options
  • • Object

  • new rule options (not mandatory).

Replace rule by name with new function & options. Throws error if name not found.

Options:

• alt - array with names of "alternate" chains.

Example

Replace existing typographer replacement rule with new one:

var md = require('markdown-it')();

md.core.ruler.at('replacements', function replace(state) {
  //...
});

• • Ruler.before(beforeName, ruleName, fn[, options])

• • beforeName
  • • String

  • new rule will be added before this one.

• • ruleName
  • • String

  • name of added rule.

• • fn
  • • Function

  • rule function.

• • options
  • • Object

  • rule options (not mandatory).

Add new rule to chain before one with given name. See also Ruler.after, Ruler.push.

Options:

• alt - array with names of "alternate" chains.

Example

var md = require('markdown-it')();

md.block.ruler.before('paragraph', 'my_rule', function replace(state) {
  //...
});

• • Ruler.disable(list[, ignoreInvalid])
  • • Array

• • list
  • • String
    • Array

  • list of rule names to disable.

• • ignoreInvalid
  • • Boolean

  • set true to ignore errors when rule not found.

Disable rules with given names. If any rule name not found - throw Error. Errors can be disabled by second param.

Returns list of found rule names (if no exception happened).

See also Ruler.enable, Ruler.enableOnly.

• • Ruler.enable(list[, ignoreInvalid])
  • • Array

• • list
  • • String
    • Array

  • list of rule names to enable.

• • ignoreInvalid
  • • Boolean

  • set true to ignore errors when rule not found.

Enable rules with given names. If any rule name not found - throw Error. Errors can be disabled by second param.

Returns list of found rule names (if no exception happened).

See also Ruler.disable, Ruler.enableOnly.

• • Ruler.enableOnly(list[, ignoreInvalid])

• • list
  • • String
    • Array

  • list of rule names to enable (whitelist).

• • ignoreInvalid
  • • Boolean

  • set true to ignore errors when rule not found.

Enable rules with given names, and disable everything else. If any rule name not found - throw Error. Errors can be disabled by second param.

See also Ruler.disable, Ruler.enable.

• • Ruler.getRules(chainName)
  • • Array

Return array of active functions (rules) for given chain name. It analyzes rules configuration, compiles caches if not exists and returns result.

Default chain name is '' (empty string). It can't be skipped. That's done intentionally, to keep signature monomorphic for high speed.

• • Ruler.push(ruleName, fn[, options])

• • ruleName
  • • String

  • name of added rule.

• • fn
  • • Function

  • rule function.

• • options
  • • Object

  • rule options (not mandatory).

Push new rule to the end of chain. See also Ruler.before, Ruler.after.

Options:

• alt - array with names of "alternate" chains.

Example

var md = require('markdown-it')();

md.core.ruler.push('my_rule', function replace(state) {
  //...
});

• • new Token(type, tag, nesting)

Create new token and fill passed properties.

• • Token.attrGet(name)

Get the value of attribute name, or null if it does not exist.

• • Token.attrIndex(name)
  • • Number

Search attribute index by name.

• • Token.attrJoin(name, value)

Join value to existing attribute via space. Or create new attribute if not exists. Useful to operate with token classes.

• • Token.attrPush(attrData)

Add [ name, value ] attribute to list. Init attrs if necessary

• • Token.attrSet(name, value)

Set name attribute to value. Override old value if exists.

• • Token#attrs
  • • Array

Html attributes. Format: [ [ name1, value1 ], [ name2, value2 ] ]

• • Token#block
  • • Boolean

True for block-level tokens, false for inline tokens. Used in renderer to calculate line breaks

• • Token#children
  • • Array

An array of child nodes (inline and img tokens)

• • Token#content
  • • String

In a case of self-closing tag (code, html, fence, etc.), it has contents of this tag.

• • Token#hidden
  • • Boolean

If it's true, ignore this element when rendering. Used for tight lists to hide paragraphs.

• • Token#info
  • • String

Additional information:

• Info string for "fence" tokens
• The value "auto" for autolink "link_open" and "link_close" tokens
• The string value of the item marker for ordered-list "list_item_open" tokens

• • Token#level
  • • Number

nesting level, the same as state.level

• • Token#map
  • • Array

Source map info. Format: [ line_begin, line_end ]

• • Token#markup
  • • String

'*' or '_' for emphasis, fence string for fence, etc.

• • Token#meta
  • • Object

A place for plugins to store an arbitrary data

• • Token#nesting
  • • Number

Level change (number in {-1, 0, 1} set), where:

• 1 means the tag is opening
• 0 means the tag is self-closing
• -1 means the tag is closing

• • Token#tag
  • • String

html tag name, e.g. "p"

• • Token#type
  • • String

Type of the token (string, e.g. "paragraph_open")