markdown

This module provides the required facilities for parsing and rendering markdown. By default, the only render target is HTML5 but all features are customizable and extendable by plugins.

Functions

markdown(preset_name, options) ⇢ Exported

Returns a new instance of class Markdown.

Parameters

• string preset_name: : optional, commonmark / zero
• dict options

Returns

• Markdown

Classes

class Token

class Token

Fields

• type ⇢ string:

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

• tag ⇢ string:

  html tag name, e.g. "p"

• attrs ⇢ list:

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

• map ⇢ list:

  Source map info. Format: [ line_begin, line_end ].

• 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

• level ⇢ number:

  nesting level, the same as state.level.

• children ⇢ list:

  A list of child nodes (inline and img tokens).

• content ⇢ string:

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

• markup ⇢ string:

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

• 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

• meta ⇢ dict:

  A place for plugins to store an arbitrary data.

• block ⇢ bool:

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

• hidden ⇢ bool:

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

Methods

Token(type, tag, nesting) ⇢ Constructor

attr_index(name)

Search attribute index by name.

@type number

attr_push(attr_data)

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

attr_set(name, value)

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

attr_get(name)

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

attr_join(name, value)

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

class Markdown

Markdown parsing and rendering class.

Usage

import markdown

var md = markdown()
echo md.render('# markdown is bae!')

Single line rendering, without paragraph wrap:

import markdown

var md = markdown()
echo md.render_inline('__markdown__ rulezz!')

Fields

• inline ⇢ InlineParser:

  Instance of [[InlineParser]]. You may need it to add new rules when writing plugins. For simple rules control use [[Markdown.disable]] and [[Markdown.enable]].

• block ⇢ BlockParser:

  Instance of [[BlockParser]]. You may need it to add new rules when writing plugins. For simple rules control use [[Markdown.disable]] and [[Markdown.enable]].

• core ⇢ BlockCore:

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

• renderer ⇢ Renderer:

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

Example

import markdown
var md = markdown()
def my_token(tokens, idx, options, env, this) {
  #...
  return result
}
md.renderer.rules['my_token'] = my_token

See [[Renderer]] docs and source code.

• validate_link:

  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:

import markdown
var md = markdown()

# enable everything
md.validate_link = @{ return true; }

@param string url @returns bool

• normalize_link:

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

@param string url @returns string

• normalize_link_text:

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

@param string url @returns string

• utils ⇢ module:

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

• helpers ⇢ dict:

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

Methods

Markdown(preset_name, options)

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

preset_name:

Markdown 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.
• standard: 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.
• xhtml_out - 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>.
• lang_prefix - 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 - nil. Highlighter def for fenced code blocks. Highlighter def (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

import markdown
# commonmark mode
var md = markdown('commonmark')
# standard mode
var md = markdown()
# enable everything
var md = markdown({
  html: true,
  linkify: true,
  typographer: true
})

Syntax highlighting

var md = markdown({
  highlight: @(str, lang) {
    if lang and get_language(lang) {
      return do_highlight(str, lang)
    }
    return '' # use external default escaping
  }
})

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

# Actual default values
var md = markdown({
  highlight: @(str, lang) {
    if lang and get_language(lang) {
      return '<pre class="hljs"><code>' +
         do_highlight(str, lang).value +
       '</code></pre>'
    }
    return '<pre class="hljs"><code>' + md.utils.escape_html(str) + '</code></pre>'
  }
})

Parameters

• string? preset_name: : commonmark, standard or zero (default: standard)
• dict? options

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

import markdown
var md = markdown().
    set({ html: true, breaks: true }).
    set({ typographer, true })

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

@chainable

Parameters

• dict options

enable(list, ignore_invalid)

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

Example

import markdown
var md = markdown().
   enable(['sub', 'sup']).
   disable('smartquotes')

@chainable

Parameters

• string|list list: : rule name or list of rule names to enable
• bool ignore_invalid: : set true to ignore errors when rule not found.

disable(list, ignore_invalid)

The same as [[Markdown.enable]], but turn specified rules off.

@chainable

Parameters

• string|list list: : rule name or list of rule names to disable.
• bool ignore_invalid: : set true to ignore errors when rule not found.

use(plugin, ...)

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

Example

import markdown
import .markdown_custom_inline

var md = markdown()
   .use(markdown_custom_inline, 'foo_replace', 'text', def(tokens, idx) {
     tokens[idx].content = tokens[idx].content.replace('/foo/', 'bar')
   })

@chainable

Parameters

• function|module plugin
• ...any params

render(src, env)

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 [[Markdown.parse]].

Parameters

• string src: : source string
• object? env: : environment sandbox

Returns

• string

render_inline(src, env)

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

Parameters

• string src: : source string
• object? env: : environment sandbox

Returns

• string

class Ruler

Helper class, used by [[markdown#core]], [[markdown#block]] and [[markdown#inline]] to manage sequences of functions (rules):

• keep rules in defined order
• assign the name to each rule
• enable/disable rules
• add/replace rules
• allow assign rules to additional named chains (in the same)
• cacheing lists of active rules You will not need use this class directly until write plugins. For simple rules control use [[markdown.disable]], [[markdown.enable]] and [[markdown.use]].

Methods

at(name, fn, options)

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

Options:

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

Example

Replace existing typographer replacement rule with new one:

import markdown as md
md.core.ruler.at('replacements', @(state) {
  #...
})

Parameters

• string name: : rule name to replace.
• function fn: : new rule function.
• dict? options: : new rule options (optional).

before(before_name, rule_name, fn, options)

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

Options:

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

Example

import markdown as md
md.block.ruler.before('paragraph', 'my_rule', @(state) {
  #...
})

Parameters

• string before_name: : new rule will be added before this one.
• string rule_name: : name of added rule.
• function fn: : rule function.
• dict? options: : rule options (optional).

after(after_name, rule_name, fn, options)

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

Options:

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

Example

import markdown as md
md.inline.ruler.after('text', 'my_rule', @(state) {
  #...
})

Parameters

• string after_name: : new rule will be added after this one.
• string rule_name: : name of added rule.
• function fn: : rule function.
• dict? options: : rule options (optional).

push(rule_name, fn, options)

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

Options:

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

Example

import markdown as md
md.core.ruler.push('my_rule', @(state) {
  #...
})

Parameters

• string rule_name: : name of added rule.
• function fn: : rule function.
• dict? options: : rule options (optional).

enable(list, ignore_invalid)

Enable rules with given names. If any rule name not found - dies Exception. Errors can be disabled by second param. Returns list of found rule names (if no exception happened). See also [[Ruler.disable]], [[Ruler.enable_only]].

Parameters

• string|list list: : list of rule names to enable.
• bool ignore_invalid: : set true to ignore errors when rule not found.

Returns

• list

enable_only(list, ignore_invalid)

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]].

Parameters

• string|list list: : list of rule names to enable (whitelist).
• bool ignore_invalid: : set true to ignore errors when rule not found.

disable(list, ignore_invalid)

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.enable_only]].

Parameters

• string|list list: : list of rule names to disable.
• bool ignore_invalid: : set true to ignore errors when rule not found.

Returns

• list

get_rules(chain_name)

Return list 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.

Parameters

• string chain_name

Returns

• string

class Renderer

Generates HTML from parsed token stream. Each instance has independent copy of rules. Those can be rewritten with ease. Also, you can add new rules if you create plugin and adds new token types.

Fields

• rules ⇢ dict:

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

Example

import markdown as md
md.renderer.rules.strong_open  = @{ return '<b>' }
md.renderer.rules.strong_close = @{ return '</b>' }
var result = md.render_inline(...)

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

def my_token_render(tokens, idx, options, env, renderer) {
  # ...
  return rendered_hTML
}

Methods

render_attrs(token)

Render token attributes to string.

Parameters

• Token token

Returns

• string

render_token(tokens, idx, options)

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

Parameters

• list tokens: : list of tokens
• number idx: : token index to render
• dict options: : params of parser instance

Returns

• string

render_inline(tokens, options, env)

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

Parameters

• list tokens: : list on block tokens to render
• dict options: : params of parser instance
• dict env: : additional data from parsed input (references, for example)

Returns

• string

render(tokens, options, env)

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

Parameters

• list tokens: : list on block tokens to render
• dict options: : params of parser instance
• dict env: : additional data from parsed input (references, for example)

Returns

• string