The Art of Layouts in Pyxie

Understanding the Layout System

In Pyxie, layouts are Python functions that transform your content into structured HTML. Each layout defines "slots" where different sections of your markdown content will be placed.

When you write a post, you use XML-style tags like <content> or <conclusion> to indicate which parts of your markdown should go into which slots in your layout. This separation of content and presentation is what makes Pyxie so flexible.

Creating Your First Layout

Let's start by creating a simple layout. Create a new file in your layouts directory called simple.py:

from fasthtml.common import *
from pyxie import layout
@layout("simple")
def simple_layout(metadata):
    """A simple blog post layout with title and content."""
    return Div(
        # Header with title from frontmatter
        H1(metadata.get('title', 'Untitled'),
           cls="text-3xl font-bold mb-8"),
        # Main content slot
        Div(None, data_slot="content",
            cls="prose dark:prose-invert"),
        cls="max-w-3xl mx-auto px-4 py-8"
    )

This layout does three important things:

It uses the @layout("simple") decorator to register the layout with Pyxie
It accesses frontmatter data through the metadata parameter
It defines a content slot with data_slot="content" where your markdown will be placed

To use this layout, you would specify it in your markdown frontmatter:

---
title: "My Post"
layout: simple
---
<content>
# My Content Heading
This is my post content.
</content>

Working with Content Slots

Slots are the key to Pyxie's layout flexibility. You can define multiple slots for different parts of your content:

@layout("advanced")
def advanced_layout(metadata):
    return Div(
        # Title section
        H1(metadata.get('title', 'Untitled'),
           cls="text-4xl font-bold"),
        # Featured image slot
        Div(None, data_slot="featured_image",
            cls="my-8"),
        # Table of contents slot
        Div(
            H2("Contents", cls="text-xl font-medium mb-4"),
            Div(None, data_slot="toc",
                cls="text-sm [&_ul]:ml-4 [&_li]:mb-2"),
            cls="my-8 p-4 bg-base-200 rounded-lg",
            data_pyxie_show="toc"  # Only show when toc slot is filled
        ),
        # Lead paragraph slot
        Div(None, data_slot="lead",
            cls="text-xl font-medium my-8",
            data_pyxie_show="lead"),
        # Main content slot
        Div(None, data_slot="content",
            cls="prose dark:prose-invert"),
        # Conclusion slot
        Div(
            H3("Conclusion", cls="text-2xl font-medium mb-4"),
            Div(None, data_slot="conclusion"),
            cls="mt-12 p-6 bg-base-200 rounded-lg",
            data_pyxie_show="conclusion"
        ),
        cls="max-w-4xl mx-auto px-4 py-12"
    )

The data_pyxie_show attribute is especially powerful - it lets you conditionally show elements only when the corresponding slot is filled. In this example, the "Contents" section only appears if the user provides a <toc> section in their markdown.

You can also use negation with the data_pyxie_show attribute by adding an exclamation mark:

# Show this message only when toc is NOT provided
Div(
    P("No table of contents available",
      cls="text-sm text-base-content/50 italic"),
    cls="my-4",
    data_pyxie_show="!toc"  # Only show when toc slot is empty
)

This negation pattern is especially useful for providing fallback content or alternative layouts when certain slots are not filled.

Styling Your Layout

Pyxie layouts use utility classes (like Tailwind CSS) for styling. This gives you complete control over the appearance of your layout:

@layout("styled")
def styled_layout(metadata):
    return Div(
        # Styled header
        Header(
            H1(metadata.get('title', 'Untitled'),
               cls="text-4xl font-bold text-primary"),
            P(metadata.get('excerpt', ''),
              cls="text-xl text-base-content/70 mt-4"),
            cls="mb-12 pb-8 border-b border-base-300/20"
        ),
        # Main content with advanced styling
        Div(None, data_slot="content",
            cls="prose prose-lg dark:prose-invert max-w-none " +
                "prose-headings:font-bold prose-h2:text-3xl " +
                "prose-p:leading-relaxed prose-a:text-primary " +
                "prose-img:rounded-xl prose-code:text-secondary"),
        cls="max-w-3xl mx-auto px-4 py-12"
    )

You can style any element in your layout, from headings and paragraphs to code blocks and images.

Layout Best Practices

As you build your layouts, keep these best practices in mind:

Use Semantic HTML
- Choose appropriate elements (<article>, <section>, etc.)
- Structure your layout logically
- Think about accessibility
Be Consistent with Slots
- Use clear, descriptive slot names
- Document which slots are available
- Provide sensible defaults for empty slots
Design Responsively
- Use relative units and breakpoints
- Test layouts on different screen sizes
- Consider both desktop and mobile experiences
Optimize for Readability
- Pay attention to font sizes, line heights, and spacing
- Ensure sufficient contrast
- Use appropriate typography for different content types

Advanced Layout Techniques

As you get more comfortable with layouts, you can explore advanced techniques:

Component Composition

Break complex layouts into smaller components for better organization:

def create_sidebar(metadata):
    return Div(
        # Sidebar content...
    )
def create_main_content():
    return Div(
        # Main content slots...
    )
@layout("composed")
def composed_layout(metadata):
    return Div(
        create_sidebar(metadata),
        create_main_content(),
        cls="grid grid-cols-12 gap-8"
    )

Dynamic Layouts

Adjust your layout based on metadata values:

@layout("dynamic")
def dynamic_layout(metadata):
    # Choose layout style based on post type
    post_type = metadata.get('type', 'standard')
    if post_type == 'feature':
        # Feature post layout
        return feature_post_layout(metadata)
    elif post_type == 'quick':
        # Quick post layout
        return quick_post_layout(metadata)
    else:
        # Standard post layout
        return standard_post_layout(metadata)

Context-Aware Styling

Apply styling based on the content's context:

@layout("context_aware")
def context_aware_layout(metadata):
    # Get post category
    category = metadata.get('category', '').lower()
    # Define category-specific colors
    colors = {
        'tutorial': 'text-blue-600',
        'opinion': 'text-amber-600',
        'news': 'text-emerald-600'
    }
    # Apply appropriate color class or default
    title_color = colors.get(category, 'text-primary')
    return Div(
        H1(metadata.get('title', 'Untitled'),
           cls=f"text-4xl font-bold {title_color}"),
        # Rest of layout...
    )

Contents

TheArtofLayoutsinPyxie