Building a Personal Blog with Pyxie

This example demonstrates how to structure blog posts using Pyxie's layout system and markdown content. We'll look at how different content sections work together and how you can customize them for your needs.

Layout Structure

This post uses a basic layout structure with several content sections:

Main content area for your markdown
Featured image placement
Optional table of contents
Conclusion section
Social sharing area

Each section is defined by XML-style tags that map to slots in your layout:

<featured_image>
  Your hero image here...
</featured_image>
<toc>
  Your table of contents...
</toc>
<content>
  Your main content...
</content>
<conclusion>
  Your conclusion...
</conclusion>
<share>
  Your sharing buttons...
</share>

Content Organization

The layout system gives you flexibility in how you organize your content. You can:

Choose which sections to include
Define your own custom sections
Style each section independently
Reorder sections as needed

Slot Naming and HTML Integration

When creating slots for your content, keep these rules in mind:

Reserved Names: Slot names cannot use standard HTML tag names like:
- Block elements: div, p, section, article
- Inline elements: span, a, strong, em
- Headings: h1 through h6
- Lists: ul, ol, li
- Tables: table, tr, td
- And other HTML tags

HTML in Content: You can still use HTML tags in your markdown:

Regular paragraph with <br> line break
<div class="custom-style">
  Styled content
</div>
List with spacing:
- Item 1<br>
- Item 2

Controlling Section Visibility

Pyxie's data-pyxie-show attribute is typically used for controlling larger layout sections. Here are common use cases:

Optional Sidebar: Show a sidebar only when sidebar content exists:

# Layout with conditional sidebar
def blog_layout(metadata):
    return Div(
        # Main content area
        Div(
            None, data_slot="content",
            cls="col-span-2"
        ),
        # Sidebar - only shows if sidebar slot is filled
        Div(
            H2("Related Posts"),
            Div(None, data_slot="sidebar"),
            cls="col-span-1",
            data_pyxie_show="sidebar"  # Entire sidebar container
        ),
        cls="grid grid-cols-3 gap-8"
    )

Layout Variations: Change layout based on frontmatter:

def article_layout(metadata):
    return Div(
        # Wide layout for feature posts
        Div(
            None, data_slot="content",
            cls="max-w-5xl",
            data_pyxie_show="is_feature"
        ),
        # Standard layout for regular posts
        Div(
            None, data_slot="content",
            cls="max-w-3xl",
            data_pyxie_show="!is_feature"
        )
    )

Used with frontmatter:

---
title: "Feature Article"
is_feature: true
---

Optional Sections: Control entire content sections:

def docs_layout(metadata):
    return Div(
        # Always show main content
        Div(None, data_slot="content"),
        # API section only shows if api slot is filled
        Div(
            H2("API Reference"),
            Div(None, data_slot="api"),
            cls="mt-12 pt-8 border-t",
            data_pyxie_show="api"
        ),
        # Examples section controlled by frontmatter
        Div(
            H2("Examples"),
            Div(None, data_slot="examples"),
            cls="mt-12",
            data_pyxie_show="show_examples"
        )
    )

The key is that data-pyxie-show typically controls the visibility of entire containers or layout sections, not just individual elements. This helps manage different layout configurations and optional content areas.

Example Post

Here's a complete example showing the basic structure:

---
title: "My First Blog Post"
date: 2024-03-24
category: Tutorials
layout: default
author: Your Name
reading_time: 5 min read
excerpt: "Learn how to create your first blog post with Pyxie"
---
<featured_image>
![Post featured image](pyxie:featured/1200/600)
</featured_image>
<toc>
- [Introduction](#introduction)
- [Main Points](#main-points)
- [Conclusion](#conclusion)
</toc>
<content>
Your post content here...
</content>
<conclusion>
Wrap up your post with a conclusion...
</conclusion>
<share>
<div class="flex gap-3">
  <a href="..." class="btn btn-sm btn-outline">
    <iconify-icon icon="fa:twitter" class="mr-2"></iconify-icon> Share
  </a>
</div>
</share>

Accessing Original Markdown

One of Pyxie's powerful features is the ability to access the original markdown source of any page by simply adding .md to the URL. This is enabled by the serve_md() middleware that's included in your FastHTML app.

How It Works

When you initialize Pyxie with the serve_md() middleware:

app, rt = fast_app(
    # other configuration...
    middleware=(pyxie.serve_md(),)  # Add markdown serving middleware
)

Pyxie automatically creates a .md endpoint for each of your content pages. For example:

A post at /article/blog-template will also be available at /article/blog-template.md
This works even if you customize the URL slug in your frontmatter

Use Cases

This feature is particularly useful for:

LLM-Optimized Content Creation: Pyxie is designed with the future of web content in mind - pages optimized for LLMs and context windows while maintaining human readability. You can have a chat with an LLM, output a markdown file, add frontmatter to define your layout, and Pyxie handles the rest.
Separation of Concerns: Pyxie cleanly separates the presentation layer (Python-defined FastHTML layouts with data-slots) from the content authoring process (markdown files). This means you can focus on writing content while maintaining complete design freedom.
Content Inspection: Easily view the original markdown source of any page to understand how content is structured and rendered.

Example

Try accessing this page's source by adding .md to the URL:

Current URL: /article/blog-template
Source URL: /article/blog-template.md

This will show you the raw markdown, including all frontmatter, xml slots, and content structure.

Customization Options

The layout system is designed to be customized. You can:

Define Your Own Layout
- Create custom content slots
- Add or remove sections
- Structure the page your way
Style Your Content
- Use any CSS framework
- Define your own typography
- Create custom components
Add Functionality
- Integrate interactive elements
- Add custom scripts
- Include third-party components

Next Steps

To enhance your blog further, check out these guides:

Content Features - Add LaTeX math, syntax highlighting, and more
The Art of Layouts - Create custom layouts for different content types
Data Visualization - Add interactive charts and graphs
Quick Start Guide - Review the basics or share with your team

These examples are just starting points - modify them to match your needs:

Building a Blog with Pyxie

Table of Contents