Metadata

Declaring metadata#

A page module exports a metadata dictionary alongside its page() function:

# app/post/page.py
metadata = {
    "title": "About Koyo",
    "description": "Koyo is a static-first Python web framework.",
    "og_image": "/images/about-card.png",
}

def page():
    ...

Supported keys:

• title: the document title.
• description: the meta description.
• og_image: the Open Graph image path.

How metadata merges#

When a page renders, Koyo collects metadata from the page and every layout it passes through, then merges key by key, nearest wins. The page overrides its immediate folder layout, which overrides the root layout, whose values act as the project defaults:

# app/layout.py, the default for every page
metadata = {
    "title": "Koyo",
    "description": "The Koyo framework.",
}

A page that only sets title keeps the root description. A nested layout can contribute defaults for its whole folder, and a page underneath can refine one key without copying the rest.

Rendering the tags#

The root layout renders the merged metadata into the head with metadata_tags():

# app/layout.py
from koyoapp.meta import metadata_tags

def layout(children, request):
    return html(lang="en")[
        head()[
            metadata_tags(),
        ],
        body[children],
    ]

Koyo holds the merged metadata for the route it is rendering, so metadata_tags() takes no arguments. It emits the title element plus the standard description and Open Graph tags (og:title, og:description, og:image), so shared pages preview correctly when linked on social platforms.