feeds.py

The markata.plugins.feeds plugin is used to create feed pages, which are lists of posts. The list is generated using a filter, then each post in the list is rendered with a card_template before being applied to the body of the template.

Installation

This plugin is built-in and enabled by default, but in you want to be very explicit you can add it to your list of existing plugins.

hooks = [
   "markata.plugins.feeds",
   ]

Configuration

set default template and card_template

At the root of the markata.feeds config you may set template, and card_template. These will become your defaults for every feed you create. If you do not set these, markata will use it's defaults. The defaults are designed to work for a variety of use cases, but are not likely the best for all.

[markata.feeds_config]
template="pages/templates/archive_template.html"
card_template="plugins/feed_card_template.html"

pages

Underneath of the markata.feeds we will create a new map for each page where the name of the map will be the name of the page.

The following config will create a page at /all-posts that inclues every single post.

[markata.feeds.all-posts]
filter="True"

template

The template configuration key is a file path to the template that you want to use to create the feed. You may set the default template you want to use for all feeds under [markata.feeds], as well as override it inside of each feeds config.

The template is a jinja style template that expects to fill in a title and body variable.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>feeds.py</title>
  </head>
  <body>
    <ul>
        
    </ul>
  </body>
</html>

Note

I highly reccomend putting your body in a <ul>, and wrapping your card_templates in an <li>.

card_template

All keys available from each post is available to put into your jinja template. These can either be placed there in your post frontmatter, or through a plugin that automatically adds to the post before the save phase.

Here is a very simple example that would give a link to each post with the title and date.

[markata.feeds.all]
filter="True"
card_template='''
<li>
    <a href=markata/plugins/feeds>
        feeds.py-
    </a>
</li>
'''

filter

The filter is a python expression ran on every post that expects to return a boolean. The variables available to this expression are every key in your frontmatter, plus the timedelta function, and parse function to more easily work with dates.

Feed Examples

True can be passed in to make a feed of all the posts you have.

[markata.feeds.archive]
filter="True"

You can compare against the values of the keys from your frontmatter. This example creates a feed that includes every post where published is True.

[markata.feeds.draft]
filter="published=='False'"

We can also compare against dates. The markata.plugins.datetime plugin, automatically adds today as today's date and now as the current datetime. These are quite handy to create feeds for scheduled, recent, or today's posts. The following two examples will create a feed for scheduled posts and for today's posts respectively.

[markata.feeds.scheduled]
filter="date>today"

[markata.feeds.today]
filter="date==today"

If you have list of items in your frontmatter for something like tags, you can check for the existence of a tag in the list.

[markata.feeds.python]
filter="date<=today and 'python' in tags"

And of course you can combine all the things into larger expressions. Here is one example of the main feed on my blog.

[markata.feeds.blog]
filter="date<=today and templateKey in ['blog-post'] and published =='True'"

Here is another example that shows my drafts for a particular tag.

[markata.feeds.python-draft]
filter="date<=today and 'python' in tags and published=='False'"

Defaults

By default feeds will create one feed page at /archive/ that includes all posts.

[markata.feeds.archive] filter="True"

SilentUndefined class

SilentUndefined source
class SilentUndefined(Undefined):
    def _fail_with_undefined_error(self, *args, **kwargs):
        return ""

MarkataFilterError class

MarkataFilterError source
class MarkataFilterError(RuntimeError):
    ...

Feed class

A storage class for markata feed objects.

Usage

from markata import Markata
m = Markata()

# access posts for a feed
m.feeds.docs.posts

# access config for a feed
m.feeds.docs.config
Feed source
class Feed:
    """
    A storage class for markata feed objects.

    ## Usage

    ``` python
    from markata import Markata
    m = Markata()

    # access posts for a feed
    m.feeds.docs.posts

    # access config for a feed
    m.feeds.docs.config
    ```
    """

    name: str
    config: Dict
    posts: list
    _m: Markata

    def map(self, func="post", **args):
        return self._m.map(func, **{**self.config, **args})

Feeds class

A storage class for all markata Feed objects

from markata import Markata
m = Markata()

m.feeds

# access all config
m.feeds.config

# refresh list of posts in all feeds
m.feeds.refresh()
# iterating over feeds gives the name of the feed
for k in m.feeds:
     print(k)

# project-gallery
# docs
# autodoc
# core_modules
# plugins
# archive

# iterate over items like keys and values in a dict, items returns name of
# feed and a feed object
for k, v in m.feeds.items():
    print(k, len(v.posts))

# project-gallery 2
# docs 6
# autodoc 65
# core_modules 26
# plugins 39
# archive 65

# values can be iterated over in just the same way
for v in m.feeds.values():
     print(len(v.posts))
# 2
# 6
# 65
# 26
# 39
# 65
```

Accessing feeds can be done using square brackets or dot notation.

``` python
from markata import Markata
m = Markata()

# both of these will return the `docs` Feed object.
m.feeds.docs
m['docs']
```
 ???+ source "Feeds <em class='small'>source</em>"
    ``` python

    class Feeds:
        """
        A storage class for all markata Feed objects

        ``` python
        from markata import Markata
        m = Markata()

        m.feeds

        # access all config
        m.feeds.config

        # refresh list of posts in all feeds
        m.feeds.refresh()


        # iterating over feeds gives the name of the feed
        for k in m.feeds:
             print(k)

        # project-gallery
        # docs
        # autodoc
        # core_modules
        # plugins
        # archive

        # iterate over items like keys and values in a dict, items returns name of
        # feed and a feed object
        for k, v in m.feeds.items():
            print(k, len(v.posts))

        # project-gallery 2
        # docs 6
        # autodoc 65
        # core_modules 26
        # plugins 39
        # archive 65

        # values can be iterated over in just the same way
        for v in m.feeds.values():
             print(len(v.posts))
        # 2
        # 6
        # 65
        # 26
        # 39
        # 65
        ```

        Accessing feeds can be done using square brackets or dot notation.

        ``` python
        from markata import Markata
        m = Markata()

        # both of these will return the `docs` Feed object.
        m.feeds.docs
        m['docs']
        ```
        """

        def __init__(self, markata: Markata):
            self._m = markata
            self.refresh()

        def refresh(self) -> None:
            """
            Refresh all of the feeds objects
            """
            self.config = self._m.config.get("feeds", dict())
            for page, page_conf in self.config.items():
                name = page.replace("-", "_").lower()
                feed = Feed(
                    name=name,
                    posts=self._m.map("post", **page_conf),
                    config=page_conf,
                    _m=self._m,
                )
                self.__setattr__(name, feed)

        def __iter__(self):
            return iter(self.config.keys())

        def keys(self):
            return iter(self.config.keys())

        def values(self):
            return [self[feed] for feed in self.config.keys()]

        def items(self):
            return [(key, self[key]) for key in self.config.keys()]

        def __getitem__(self, key: str) -> Any:
            return getattr(self, key.replace("-", "_").lower())

        def _dict_panel(self, config) -> str:
            """
            pretty print configs with rich
            """
            msg = ""
            for key, value in config.items():
                msg = msg + f"[grey46]{key}[/][magenta3]:[/] [grey66]{value}[/]\n"
            return msg

        def __rich__(self) -> Table:
            from rich.table import Table

            table = Table(title=f"Feeds {len(self.config)}")

            table.add_column("Feed", justify="right", style="cyan", no_wrap=True)
            table.add_column("posts", justify="left", style="green")
            table.add_column("config", style="magenta")

            for name in self.config.keys():
                table.add_row(
                    name, str(len(self[name].posts)), self._dict_panel(self.config[name])
                )
            return table
    ```

configure function

configure the default values for the feeds plugin

configure source
def configure(markata: Markata) -> None:
    """
    configure the default values for the feeds plugin
    """
    if "feeds" not in markata.config.keys():
        markata.config["feeds"] = dict()
    config = markata.config.get("feeds", dict())
    if "archive" not in config.keys():
        config["archive"] = dict()
        config["archive"]["filter"] = "True"

    default_post_template = markata.config.get("feeds_config", {}).get(
        "template", Path(__file__).parent / "default_post_template.html"
    )

    for page, page_conf in config.items():
        if "template" not in page_conf.keys():
            page_conf["template"] = default_post_template

pre_render function

Create the Feeds object and attach it to markata.

pre_render source
def pre_render(markata: Markata) -> None:
    """
    Create the Feeds object and attach it to markata.
    """
    markata.feeds = Feeds(markata)

save function

Creates a new feed page for each page in the config.

save source
def save(markata: Markata) -> None:
    """
    Creates a new feed page for each page in the config.
    """
    feeds = markata.config.get("feeds", {})

    description = markata.get_config("description") or ""
    url = markata.get_config("url") or ""

    for page, page_conf in feeds.items():
        create_page(
            markata,
            page,
            description=description,
            url=url,
            **page_conf,
        )

    home = Path(str(markata.config["output_dir"])) / "index.html"
    archive = Path(str(markata.config["output_dir"])) / "archive" / "index.html"
    if not home.exists() and archive.exists():
        shutil.copy(str(archive), str(home))

create_page function

create an html unorderd list of posts.

create_page source
def create_page(
    markata: Markata,
    page: str,
    tags: Optional[List] = None,
    published: str = "True",
    template: Optional[Union[Path, str]] = None,
    card_template: Optional[str] = None,
    filter: Optional[str] = None,
    description: Optional[str] = None,
    url: Optional[str] = None,
    title: Optional[str] = "feed",
    sort: str = "True",
    reverse: bool = False,
    **rest,
) -> None:
    """
    create an html unorderd list of posts.
    """

    posts = markata.feeds[page].posts
    cards = [create_card(markata, post, card_template) for post in posts]
    cards.insert(0, "<ul>")
    cards.append("</ul>")

    # if template is None:
    #     template = Path(__file__).parent / "default_post_template.html"

    with open(template) as f:
        template = Template(f.read(), undefined=SilentUndefined)
    output_file = Path(markata.config["output_dir"]) / page / "index.html"
    canonical_url = f"{url}/{page}/"
    output_file.parent.mkdir(exist_ok=True, parents=True)

    with open(output_file, "w+") as f:
        f.write(
            template.render(
                markata=markata,
                __version__=__version__,
                body="".join(cards),
                url=url,
                description=description,
                title=title,
                canonical_url=canonical_url,
                today=datetime.datetime.today(),
                config=markata.config,
            )
        )

create_card function

Creates a card for one post based on the configured template. If no template is configured it will create one with the post title and dates (if present).

create_card source
def create_card(
    markata: "Markata", post: "Post", template: Optional[str] = None
) -> Any:
    """
    Creates a card for one post based on the configured template.  If no
    template is configured it will create one with the post title and dates
    (if present).
    """
    if template is None:
        template = markata.config.get("feeds_config", {}).get("card_template", None)

    if template is None:
        if "date" in post.keys():
            return textwrap.dedent(
                f"""
                <li class='post'>
                <a href="/{markata.config.get('path_prefix', '')}{post['slug']}/">
                    {post['title']}
                    {post['date'].year}-
                    {post['date'].month}-
                    {post['date'].day}
                </a>
                </li>
                """
            )
        else:
            return textwrap.dedent(
                f"""
                <li class='post'>
                <a href="/{markata.config.get('path_prefix', '')}{post['slug']}/">
                    {post['title']}
                </a>
                </li>
                """
            )
    try:
        _template = Template(Path(template).read_text())
    except FileNotFoundError:
        _template = Template(template)
    return _template.render(markata=markata, **post.to_dict())

cli function

cli source
def cli(app: typer.Typer, markata: "Markata") -> None:
    feeds_app = typer.Typer()
    app.add_typer(feeds_app)

    @feeds_app.callback()
    def feeds():
        "feeds cli"

    @feeds_app.command()
    def show() -> None:
        markata.console.quiet = True
        feeds = markata.feeds
        markata.console.quiet = False
        rich_print(feeds)

_fail_with_undefined_error method

_fail_with_undefined_error source
def _fail_with_undefined_error(self, *args, **kwargs):
        return ""

map method

map source
def map(self, func="post", **args):
        return self._m.map(func, **{**self.config, **args})

init method

init source
def __init__(self, markata: Markata):
        self._m = markata
        self.refresh()

refresh method

Refresh all of the feeds objects

refresh source
def refresh(self) -> None:
        """
        Refresh all of the feeds objects
        """
        self.config = self._m.config.get("feeds", dict())
        for page, page_conf in self.config.items():
            name = page.replace("-", "_").lower()
            feed = Feed(
                name=name,
                posts=self._m.map("post", **page_conf),
                config=page_conf,
                _m=self._m,
            )
            self.__setattr__(name, feed)

iter method

iter source
def __iter__(self):
        return iter(self.config.keys())

keys method

keys source
def keys(self):
        return iter(self.config.keys())

values method

values source
def values(self):
        return [self[feed] for feed in self.config.keys()]

items method

items source
def items(self):
        return [(key, self[key]) for key in self.config.keys()]

getitem method

getitem source
def __getitem__(self, key: str) -> Any:
        return getattr(self, key.replace("-", "_").lower())

_dict_panel method

pretty print configs with rich

_dict_panel source
def _dict_panel(self, config) -> str:
        """
        pretty print configs with rich
        """
        msg = ""
        for key, value in config.items():
            msg = msg + f"[grey46]{key}[/][magenta3]:[/] [grey66]{value}[/]\n"
        return msg

rich method

rich source
def __rich__(self) -> Table:
        from rich.table import Table

        table = Table(title=f"Feeds {len(self.config)}")

        table.add_column("Feed", justify="right", style="cyan", no_wrap=True)
        table.add_column("posts", justify="left", style="green")
        table.add_column("config", style="magenta")

        for name in self.config.keys():
            table.add_row(
                name, str(len(self[name].posts)), self._dict_panel(self.config[name])
            )
        return table

feeds function

feeds cli

feeds source
def feeds():
        "feeds cli"

show function

show source
def show() -> None:
        markata.console.quiet = True
        feeds = markata.feeds
        markata.console.quiet = False
        rich_print(feeds)