Next | Previous

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.markdown(preset_name, options) ➝ Exported

Returns a new instance of class Markdown.

  • @params:

    • string preset_name optional, commonmark / zero

    • dict options

  • @returns: Markdown

Classes

class Token

class Token

@serializable

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

.Token(type, tag, nesting) ➝ Constructor

markdown.Token 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.

.to_dict()

Returns the Token properties as a dictionary.

  • @returns: dict
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!')
.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.

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

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

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.

.Markdown(preset_name, options)

Creates parser instance 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 auto convert URL-like text to links.
  • typographer - false. Set true to enable some language-neutral replacement + quotes beautification (smart quotes).
  • quotes - “”‘’, String or Array. Double + single quotes replacement pairs, when typographer enabled and smart quotes 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 externally. 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>'
  }
})
  • @params:

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

  • @params:
    • 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')
  • @params:

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

  • @params:

    • 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')
   })
  • @params:
    • 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. 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.

  • @params:

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

  • @params:

    • 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)
  • caching 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.
.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) {
  #...
})
  • @params:

    • 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) {
  #...
})
  • @params:

    • 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) {
  #...
})
  • @params:

    • 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) {
  #...
})
  • @params:

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

  • @params:

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

  • @params:

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

  • @params:

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

  • @params:
    • 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.

.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
}
.render_attrs(token)

Render token attributes to string.

  • @params:
    • Token token
  • @returns: string
.render_token(tokens, idx, options)

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

  • @params:

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

  • @params:

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

  • @params:

    • 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