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
- parser: an instance of
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 inmarko.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 aftersuper().__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 theelement_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.
- be named as
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
-
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
-
classmethod
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.
-
classmethod
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.
-
classmethod
-
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.
-