API References

Main Class

class marko.Markdown(parser: type[Parser] = <class 'marko.parser.Parser'>, renderer: type[Renderer] = <class 'marko.html_renderer.HTMLRenderer'>, extensions: Any | 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 marko.parser.Parser.
• renderer – a subclass marko.renderer.Renderer.
• extensions – a list of extensions to register on the object. See document of Markdown.use().

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) → 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 – 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: 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(source_or_text: Source | AnyStr) → list[block.BlockElement] | block.BlockElement

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: str) → list[inline.InlineElement]

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

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

inline_children = False

Whether children are parsed as inline elements.

classmethod match(source: marko.helpers.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 = False

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

classmethod parse(source: marko.helpers.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

parse_inline() → None

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.

Block level elements

class marko.block.Document(text: str)

Document node element.

class marko.block.CodeBlock(lines: str)

Indented code block: ( this is a code block )

classmethod match(source: marko.helpers.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: marko.helpers.Source) → str

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

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

Heading element: (### Hello )

classmethod match(source: Source) → Match | 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 | None

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

class marko.block.List

List block element

classmethod match(source: marko.helpers.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: marko.helpers.Source) → marko.block.List

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

class marko.block.ListItem

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

classmethod match(source: marko.helpers.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: marko.helpers.Source) → marko.block.ListItem

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

class marko.block.BlankLine(start: int)

Blank lines

classmethod match(source: marko.helpers.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: marko.helpers.Source) → int

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

class marko.block.Quote

block quote element: (> hello world)

classmethod match(source: Source) → Match | 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: marko.helpers.Source) → marko.block.Quote

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

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

Fenced code block: (`python hello ` )

classmethod match(source: Source) → Match | 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]

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

class marko.block.ThematicBreak

Horizontal rules: (—- )

classmethod match(source: marko.helpers.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: marko.helpers.Source) → marko.block.ThematicBreak

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

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: marko.helpers.Source) → str

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

class marko.block.LinkRefDef

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

classmethod match(source: marko.helpers.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: marko.helpers.Source) → marko.block.LinkRefDef

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

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

Setext heading: (Hello === )

It can only be created by Paragraph.parse.

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

A paragraph element

classmethod match(source: marko.helpers.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]

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

Inline Elements

class marko.inline.InlineElement(match: _Match)

Any inline element should inherit this class

classmethod find(text: str) → Iterator[Match[AnyStr]]

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

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 = ''

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.LineBreak(match: _Match)

Line breaks:

Soft: ‘

‘

Hard: ‘

‘

class marko.inline.Literal(match: _Match)

Literal escapes need to be parsed at the first.

class marko.inline.LinkOrEmph(match: _Match)

This is a special element, whose parsing is done specially. And it produces Link or Emphasis elements.

classmethod find(text: str) → Iterator[Match[AnyStr]]

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

class marko.inline.InlineHTML(match: _Match)

class marko.inline.CodeSpan(match: _Match)

Inline code span: code sample

class marko.inline.Emphasis(match: _Match)

Emphasis: sample text

class marko.inline.StrongEmphasis(match: _Match)

Strong emphasis: sample text

class marko.inline.Link(match: _Match)

Link: [text](/link/destination)

class marko.inline.Image(match: _Match)

Image: 

class marko.inline.AutoLink(match: _Match)

Autolinks: <http://example.org>

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

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

Helper Classes

class marko.helpers.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.

exhausted

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.

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: bool = 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.

prefix

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.

root

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

state

Returns the current element state.

under_state(element: BlockElement) → Generator[Source, None, None]

A context manager to enable a new state temporarily.