API References

Main Class

class marko.Markdown(parser=<class 'marko.parser.Parser'>, renderer=<class 'marko.html_renderer.HTMLRenderer'>, extensions=None)

The main class to convert markdown documents.

Attributes:
Parameters:
convert(text)

Parse and render the given text.

parse(text)

Call self.parser.parse(text).

Override this to preprocess text or handle parsed result.

render(parsed)

Call self.renderer.render(text).

Override this to handle parsed result.

use(*extensions)

Register extensions to Markdown object. An extension should be either an object providing elements, parser_mixins` , renderer_mixins or all attributes, or a string representing the corresponding extension in marko.ext module.

Parameters:*extensions – extension object or string.

Note

Marko uses a mixin based extension system, the order of extensions matters: An extension preceding in order will have higher priorty.

Parser Class

class marko.parser.Parser

All elements defined in CommonMark’s spec are included in the parser by default.

Attributes:
block_elements(dict): a dict of name: block_element pairs inline_elements(dict): a dict of name: inline_element pairs
Parameters:*extras – extra elements to be included in parsing process.
add_element(element)

Add an element to the parser.

Parameters:element – the element class.

Note

If one needs to call it inside __init__(), please call it after super().__init__() is called.

parse(source_or_text)

Do the actual parsing and returns an AST or parsed element.

Parameters:source_or_text – the text or source object. Based on the type, it will do following: - text: returns the parsed Document element. - source: parse the source and returns the parsed children as a list.
parse_inline(text)

Parses text into inline elements. RawText is not considered in parsing but created as a wrapper of holes that don’t match any other elements.

Parameters:text – the text to be parsed.
Returns:a list of inline elements.

Renderer Class

class marko.renderer.Renderer

The base class of renderers.

A custom renderer should subclass this class and include your own render functions.

A render function should:

  • be named as render_<element_name>, where the element_name is the snake case form of the element class name, the renderer will search the corresponding function in this way.
  • accept the element instance and return any output you want.

If no corresponding render function is found, renderer will fallback to call Renderer.render_children().

delegate = True

Whether to delegate rendering to specific render functions

render(element)

Renders the given element to string.

Parameters:element – a element to be rendered.
Returns:the output string or any values.
render_children(element)

Recursively renders child elements. Joins the rendered strings with no space in between.

If newlines / spaces are needed between elements, add them in their respective templates, or override this function in the renderer subclass, so that whitespace won’t seem to appear magically for anyone reading your program.

Parameters:element – a branch node who has children attribute.

Base Elements

class marko.block.BlockElement

Any block element should inherit this class

classmethod get_type(snake_case=False)

Return the Markdown element type that the object represents.

Parameters:snake_case – Return the element type name in snake case if True
inline_children = False

Whether children are parsed as inline elements.

classmethod match(source)

Test if the source matches the element at current position. The source should not be consumed in the method unless you have to.

Parameters:source – the Source object of the content to be parsed
override = False

If true, will replace the element which it derives from.

classmethod parse(source)

Parses the source. This is a proper place to consume the source body and return an element or information to build one. The information tuple will be passed to __init__ method afterwards. Inline parsing, if any, should also be performed here.

Parameters:source – the Source object of the content to be parsed
parse_inline()

Inline parsing is postponed so that all link references are seen before that.

priority = 5

Use to denote the precedence in parsing

virtual = False

if True, it won’t be included in parsing process but produced by other elements other elements instead.

class marko.inline.InlineElement(match)

Any inline element should inherit this class

classmethod find(text)

This method should return an iterable containing matches of this element.

classmethod get_type(snake_case=False)

Return the Markdown element type that the object represents.

Parameters:snake_case – Return the element type name in snake case if True
override = False

If true, will replace the element which it derives from.

parse_children = False

whether to parse children.

parse_group = 1

which match group to parse.

pattern = None

element regex pattern.

priority = 5

Use to denote the precedence in parsing.

virtual = False

if True, it won’t be included in parsing process but produced by other elements instead.

Helper Classes

class marko.helpers.Source(text)

Wrapper class on content to be parsed

anchor()

Pin the current parsing position.

consume()

Consume the body of source. pos will move forward.

exhausted

Indicates whether the source reaches the end.

expect_re(regexp)

Test against the given regular expression and returns the match object.

Parameters:regexp – the expression to be tested.
Returns:the match object.
match_prefix

Check if the line starts with given prefix and return the position of the end of prefix. If the prefix is not matched, return -1.

next_line(require_prefix=True)

Return the next line in the source.

Parameters:require_prefix – if False, the whole line will be returned. otherwise, return the line with prefix stripped or None if the prefix is not matched.
pop_state()

Pop the top most state.

prefix

The prefix of each line when parsing.

push_state(element)

Push a new state to the state stack.

reset()

Reset the position to the last anchor.

root

Returns the root element, which is at the bottom of self._states.

state

Returns the current element state.

under_state(element)

A context manager to enable a new state temporarily.