API Reference¶

Main Class¶

class marko.Markdown(parser: type[marko.parser.Parser] = <class 'marko.parser.Parser'>, renderer: type[marko.renderer.Renderer] = <class 'marko.html_renderer.HTMLRenderer'>, extensions: ~typing.Iterable[str | ~marko.helpers.MarkoExtension] | None = None)¶

The main class to convert markdown documents.

Attributes:

parser: an instance of marko.parser.Parser
renderer: an instance of marko.renderer.Renderer

Parameters:

parser – a subclass of marko.parser.Parser.
renderer – a subclass of marko.renderer.Renderer.
extensions – a list of extensions to register on the object. See document of Markdown.use().

Note

This class is not thread-safe. Create a new instance for each thread.

convert(text: str) → str¶: Parse and render the given text.

parse(text: str) → Document¶

Call self.parser.parse(text).

Override this to preprocess text or handle parsed result.

render(parsed: Document) → str¶

Call self.renderer.render(text).

Override this to handle parsed result.

use(*extensions: str | MarkoExtension) → None¶

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 – string or marko.helpers.MarkoExtension object.

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: ElementType) → None¶

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(text: str) → Document¶

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

Parameters:: text – the text to parse.
Returns:: the parsed root element

parse_inline(element: BlockElement, source: Source) → None¶: Inline parsing is postponed so that all link references are seen before that.

parse_source(source: Source) → list[marko.block.BlockElement]¶: Parse the source into a list of block 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().

render(element: Element) → Any¶

Renders the given element to string.

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

render_children(element: Any) → Any¶

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.

Elements¶

Block Elements¶

class marko.block.BlockElement¶

Any block element should inherit this class

children: Sequence[Element] = []¶: An attribute to hold the children

inline_body: str = ''¶: If not empty, the body needs to be parsed as inline elements

classmethod match(source: Source) → Any¶

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: bool = False¶: If true, will replace the element which it derives from.

classmethod parse(source: Source) → Any¶

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

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.

Block level elements

class marko.block.BlankLine(start: int)¶

Blank lines

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → int¶

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

priority = 5¶: Use to denote the precedence in parsing

class marko.block.CodeBlock(lines: str)¶

Indented code block: ( this is a code block )

classmethod match(source: Source) → str¶

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

classmethod parse(source: Source) → str¶

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

priority = 4¶: Use to denote the precedence in parsing

class marko.block.Document¶

Document node element.

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

class marko.block.FencedCode(match: tuple[str, str, str])¶

Fenced code block: (`python hello ` )

class ParseInfo(prefix, leading, lang, extra)¶

extra: str¶: Alias for field number 3

lang: str¶: Alias for field number 2

leading: str¶: Alias for field number 1

prefix: str¶: Alias for field number 0

classmethod match(source: Source) → Match[str] | None¶

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

classmethod parse(source: Source) → tuple[str, str, str]¶

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

priority = 7¶: Use to denote the precedence in parsing

class marko.block.HTMLBlock(lines: str)¶

HTML blocks, parsed as it is

classmethod match(source: Source) → int | bool¶

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

classmethod parse(source: Source) → str¶

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

priority = 5¶: Use to denote the precedence in parsing

class marko.block.Heading(match: Match[str])¶

Heading element: (### Hello )

classmethod match(source: Source) → Match[str] | None¶

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

classmethod parse(source: Source) → Match[str] | None¶

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

priority = 6¶: Use to denote the precedence in parsing

class marko.block.LinkRefDef(label: str, text: str, title: str | None = None)¶

Link reference definition: [label]: destination “title”

class ParseInfo(link_label, link_dest, link_title, end)¶

end: int¶: Alias for field number 3

link_dest: Group¶: Alias for field number 1

link_label: Group¶: Alias for field number 0

link_title: Group¶: Alias for field number 2

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → LinkRefDef¶

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

class marko.block.List(info: ParseInfo)¶

List block element

class ParseInfo(bullet, ordered, start)¶

bullet: str¶: Alias for field number 0

ordered: bool¶: Alias for field number 1

start: int¶: Alias for field number 2

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → List¶

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

priority = 6¶: Use to denote the precedence in parsing

class marko.block.ListItem(info: ParseInfo)¶

List item element. It can only be created by List.parse

class ParseInfo(indent, bullet, mid)¶

bullet: str¶: Alias for field number 1

indent: int¶: Alias for field number 0

mid: int¶: Alias for field number 2

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → ListItem¶

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

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

class marko.block.Paragraph(lines: list[str])¶

A paragraph element

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → list[str] | SetextHeading¶

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

priority = 1¶: Use to denote the precedence in parsing

class marko.block.Quote¶

block quote element: (> hello world)

classmethod match(source: Source) → Match[str] | None¶

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

classmethod parse(source: Source) → Quote¶

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

priority = 6¶: Use to denote the precedence in parsing

class marko.block.SetextHeading(lines: list[str])¶

Setext heading: (Hello === )

It can only be created by Paragraph.parse.

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

class marko.block.ThematicBreak¶

Horizontal rules: (—- )

classmethod match(source: Source) → bool¶

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

classmethod parse(source: Source) → ThematicBreak¶

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

priority = 8¶: Use to denote the precedence in parsing

Inline Elements¶

class marko.inline.InlineElement(match: _Match)¶

Any inline element should inherit this class

classmethod find(text: str, *, source: Source) → Iterator[_Match]¶: This method should return an iterable containing matches of this element.

override: bool = 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: Pattern[str] | str = ''¶: 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.

Inline(span) level elements

class marko.inline.AutoLink(match: _Match)¶

Autolinks: <http://example.org>

pattern: Pattern[str] | str = re.compile("<([A-Za-z][A-Za-z\\-.+]{1,31}:[^\\s<>]*?|[a-zA-Z0-9.!#$%&\\'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*)>")¶: element regex pattern.

priority = 7¶: Use to denote the precedence in parsing.

class marko.inline.CodeSpan(match: _Match)¶

Inline code span: code sample

pattern: Pattern[str] | str = re.compile('(?<!`)(`+)(?!`)([\\s\\S]+?)(?<!`)\\1(?!`)')¶: element regex pattern.

priority = 7¶: Use to denote the precedence in parsing.

class marko.inline.Emphasis(match: _Match)¶

Emphasis: sample text

parse_children = True¶: whether to parse children.

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

class marko.inline.Image(match: _Match)¶

Image: ![alt](/src/address)

parse_children = True¶: whether to parse children.

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

class marko.inline.InlineHTML(match: _Match)¶

pattern: Pattern[str] | str = re.compile('(<[A-Za-z][A-Za-z0-9\\-]*(?:\\s+[A-Za-z:_][A-Za-z0-9\\-_\\.:]*(?:\\s*=\\s*(?:[^\\s"\\\'`=<>]+|\\\'[^\\\']*\\\'|"[^"]*"))?)* */?>|</[A-Za-z][A-Za-z0-9\\-]* *>|)|<\\?[\\s\\S]*?)¶: element regex pattern.

priority = 7¶: Use to denote the precedence in parsing.

class marko.inline.LineBreak(match: _Match)¶

Line breaks:

Soft: ‘

‘: Hard: ‘

‘

pattern: Pattern[str] | str = '( *|\\\\)\\n(?!\\Z)'¶: element regex pattern.

priority = 2¶: Use to denote the precedence in parsing.

class marko.inline.Link(match: _Match)¶

Link: [text](/link/destination)

parse_children = True¶: whether to parse children.

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

class marko.inline.Literal(match: _Match)¶

Literal escapes need to be parsed at the first.

pattern: Pattern[str] | str = re.compile('\\\\([!"#\\$%&\\\'()*+,\\-./:;<=>?@\\[\\\\\\]^_`{|}~])')¶: element regex pattern.

priority = 7¶: Use to denote the precedence in parsing.

class marko.inline.RawText(match: str, escape: bool = True)¶

The raw text is the fallback for all holes that doesn’t match any others.

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

class marko.inline.StrongEmphasis(match: _Match)¶

Strong emphasis: sample text

parse_children = True¶: whether to parse children.

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

Helper Classes¶

class marko.source.Source(text: str)¶

Wrapper class on content to be parsed

anchor() → None¶: Pin the current parsing position.

consume() → None¶: Consume the body of source. pos will move forward.

context¶: Store temporary data during parsing.

property exhausted: bool¶: Indicates whether the source reaches the end.

expect_re(regexp: Pattern[str] | str) → Match[str] | None¶: Test against the given regular expression and returns the match object. :param regexp: the expression to be tested. :returns: the match object.

static match_prefix(prefix: str, line: str) → int¶: 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: Literal[False] = True) → str¶

next_line(require_prefix: Literal[True] = True) → str | None

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() → BlockElement¶: Pop the top most state.

property prefix: str¶: The prefix of each line when parsing.

push_state(element: BlockElement) → None¶: Push a new state to the state stack.

reset() → None¶: Reset the position to the last anchor.

property root: Document¶: Returns the root element, which is at the bottom of self._states.

property state: BlockElement¶: Returns the current element state.

under_state(element: BlockElement) → Generator[Source, None, None]¶: A context manager to enable a new state temporarily.

class marko.helpers.MarkoExtension(parser_mixins: 'list[type]' = <factory>, renderer_mixins: 'list[type]' = <factory>, elements: 'list[type[Element]]' = <factory>)¶