Parsers

Parsers control how content is parsed and rendered.

All Page and Collection objects have a parser attribute that is used to parse the content of the object.

Parsers use staticmethods to parse content. This allows you to create custom parsers that can be used to parse content in any way you want. Render Engine comes with a BasePageParser and a MarkdownPageParser that can be used out of the box.

BasePageParser

The default Parser for Page objects. This yields attributes and content using frontmatter. The content is not modified.

Functions

parse(content, page=None) staticmethod

Parses content to be rendered into HTML

In the base parser, this returns the content as is.

Parameters:

Name	Type	Description	Default
content	str	content to be rendered into HTML	required
page	Page	Page object to gain access to attributes	None

parse_content(content) staticmethod

Fetches content from Page.content and returns attributes and content.

This is a separate method so that it can be overridden by subclasses.

Parameters:

Name	Type	Description	Default
content	str	The path to the file that will be used to generate the Page's content. Should be a valid path to a file or a url.	required

parse_content_path(content_path) staticmethod

Fetches content from Page.content_path and sets attributes.

This is a separate method so that it can be overridden by subclasses.

Parameters:

Name	Type	Description	Default
content_path	str	The path to the file that will be used to generate the Page's content. Should be a valid path to a file or a url.	required

from render_engine.parsers.base_parsers import BasePageParser
from render_engine.page import Page

base_text = """ 
---
title: "Hello World"
---

This is base content
"""

class MyPage(Page):
    parser = BasePageParser
    content = base_text

my_page = MyPage()
my_page.title
>>> "Hello World"

my_page.content
>>> "This is base content"

my_page._render_content()
>>> "This is base content"

MarkdownPageParser

In many cases you will want to create rich content. Render Engine comes with a MarkdownPageParser that can be used to parse Markdown files. You can also pass in attributes to the page via frontmatter at the top of the markdown file.

from render_engine.parsers.base_parsers import BasePageParser
from render_engine.page import Page

base_markdown = """ 
---
title: "Hello World"
---

This is **dynamic** content
"""

class MyPage(Page):
    parser = BasePageParser
    content = base_text

my_page = MyPage()
my_page.title
>>> "Hello World"

my_page.content
>>> "This is **dynamic** content"

my_page._render_content()
>>> "<p>This is <strong>dynamic</strong> content</p>"

Creating Custom Parsers

You can create custom parsers by subclassing BasePageParser.

All the static methods for parsers should return a tuple where the first entry is a dictionary of attributes and the sencond entry is the rendered content.

Warning

Custom Parsers do not use frontmatter by default. You would need to ensure that your parser handles frontmatter if you want to use it.

For example, to create a parser that renders a dictionary, you could do the following:

from src.render_engine.parsers.base_parsers import BasePageParser

class DictPageParser(BasePageParser):
    @staticmethod
    def parse_content(base_content: dict) -> dict:
        content = base_content.pop("content", "")
        return (base_content, content)

    # `parse_content_path` would be similar in this case.
    # `parse` would be inherited from `BasePageParser`  

base_dict = {
    "title": "Hello World"
    "content": This is base content
}

class MyPage(Page):
    parser = DictPageParser
    content = base_dict

my_page = MyPage()
my_page.title
>>> "Hello World"

my_page.content
>>> "This is base content"

my_page._render_content()
>>> "This is base content"