marko Documentation

Marko distinguishes between two types of elements in the AST:

• Block Elements: Managed via marko.block.BlockElement. These represent structural components like paragraphs, lists, or headers.
• Inline Elements: Managed via marko.inline.InlineElement. These represent content within blocks, such as emphasis, strong text, or links.

You can access the parsed document structure using the .parse() method. This returns a tree of objects that can be traversed to inspect elements like headings, paragraphs, and their properties (e.g., heading levels).

from marko import Markdown

md = Markdown()
doc = md.parse("# Title\n\nParagraph with **bold** text.")

# The document has a tree structure
print(doc)  # Document object
print(doc.children)  # List of block elements

# Access specific elements
heading = doc.children[0]  # Heading element
print(heading.level)  # 1
print(heading.children)  # ['Title']

paragraph = doc.children[1]  # Paragraph element
print(paragraph.children)  # List of inline elements

To allow users to refer to your extension via an import string (e.g., Markdown(extensions=['my_package'])) instead of importing the object directly, include a make_extension(arg) function in your package's entry file. This function should accept arguments and return a MarkoExtension object.

def make_extension(arg):
    return GitHubWiki(arg)

To add support for new syntax like GitHub wiki links ([[Page|Target]]), subclass marko.inline.InlineElement.

Key attributes:

• pattern: A regex string used to scan text for matches.
• parse_children: If True, the parser will parse the content within the match groups (defaulting to group 1) into inline elements.
• priority: Controls parsing precedence. The default is 5. Higher numbers are tried sooner. If priorities are equal, the first registered element wins.
• override: Set to True if you want to replace an existing element's functionality.

Use the __init__(self, match) method to map regex match groups to element attributes.

from marko import inline

class GitHubWiki(inline.InlineElement):
    pattern = r'\\\[\\[ *(.+?) *\| *(.+?) *\\\]\\]'
    parse_children = True

    def __init__(self, match):
        self.target = match.group(2)

Marko provides several built-in extensions to add specialized Markdown parsing capabilities. You can enable these extensions by importing the specific extension module and adding it to your Marko instance.

Available built-in extensions include:

• marko.ext.gfm: GitHub Flavored Markdown support.
• marko.ext.toc: Table of Contents generation.
• marko.ext.footnote: Footnote support.
• marko.ext.pangu: Pangu support (improves spacing for CJK characters).
• marko.ext.codehilite: Syntax highlighting for code blocks.

To convert Markdown text to HTML in your Python code, import marko and use the marko.convert() function.

import marko

print(marko.convert(text))

You can intercept the parsing or rendering lifecycle by subclassing marko.Markdown:

• Pre-processing: Override the parse(self, text) method to modify the raw text before it is parsed.
• Post-processing: Override the render(self, parsed) method to modify the output (e.g., HTML) after the rendering process is complete.

from marko import Markdown

# Pre-processing Text
class MyMarkdown(Markdown):
    def parse(self, text):
        # Pre-process text before parsing
        text = text.replace('TODO:', '**TODO:**')
        return super().parse(text)

# Post-processing Results
class MyPostProcessor(Markdown):
    def render(self, parsed):
        html = super().render(parsed)
        # Post-process HTML
        return html.replace('<p>', '<p class="content">')

md = MyPostProcessor()
html = md.convert("Hello world")

Install Marko using pip. Marko requires Python 3.7 or higher.

$ pip install marko

The simplest way to convert Markdown text to HTML is by using the marko.convert() convenience function. This is ideal for one-off conversions where you don't need custom configuration.

import marko

# Convert markdown to HTML
html = marko.convert("# Hello World\nThis is **bold** text.")
print(html)
# Output: <h1 Hello World</h1>\n<p>This is <strong>bold</strong> text.</p>\n

Extensions can add new elements or modify parsing/rendering. You can load them in three ways:

1. During initialization: Pass a list of extension names to the extensions argument in Markdown().
2. Using the .use() method: Call md.use('extension_name') on an existing instance.
3. Passing extension objects: Pass the result of an extension factory (e.g., make_extension()) to the extensions list.

from marko import Markdown

# Method 1: Pass extensions during initialization
md = Markdown(extensions=['footnote', 'toc'])

# Method 2: Use the use() method
md = Markdown()
md.use('footnote')
md.use('toc')

# Method 3: Pass extension objects
from marko.ext.footnote import make_extension
md = Markdown(extensions=[make_extension()])