Quick Start Guide: Build Your First Pyxie Site

Welcome to Pyxie! This guide will help you create your first site by combining the simplicity of Markdown with the power of FastHTML layouts.

Prerequisites

Before we begin, make sure you have:

• Python 3.11 or higher

• Basic knowledge of Markdown and Python

• A text editor of your choice

Installation

Install Pyxie using pip:

pip install pyx2

Project Setup

Create a new directory for your site and set up a basic structure:

my-site/
├── posts/          # Your markdown content
├── layouts/        # Your layout files
├── static/
│   └── css/       # Your CSS files
└── main.py        # App initialization

Create your app initialization file (main.py):

from fasthtml.common import *
from pyxie import Pyxie
# Initialize Pyxie with content and layout directories
pyxie = Pyxie(
    "posts",                # Where to find your markdown content
    live=True              # Enable live reloading for development
)
# Create FastHTML app with Pyxie middleware
app, rt = fast_app(
    htmlkw=dict(lang="en"),
    middleware=(pyxie.serve_md(),)  # Serve markdown versions at {slug}.md
)

The live=True parameter enables automatic reloading during development:

• Your browser will refresh when you save changes to markdown files

• Changes to layouts and components are also detected

• Perfect for rapid iteration and content editing

• Be sure to disable for production

The serve_md() middleware automatically makes your original markdown content available at a .md endpoint. For example:

• Your post at /blog/hello will also be available at /blog/hello.md

• This works even if you customize the URL slug in your frontmatter

• Perfect for LLMs and other tools that need access to the raw markdown

That's it! Pyxie will automatically:

• Find layouts in layouts/, templates/, or static/ directories

• Use the "default" layout if none is specified

For better performance on larger sites, you should enable caching:

pyxie = Pyxie(
    "posts",
    cache_dir=".cache",            # Enable caching (recommended for production)
    default_layout="blog",         # Change the default layout
    layout_paths=["custom/layouts"] # Use custom layout directories
)

Important: Caching is not enabled by default. Without the cache_dir parameter, Pyxie will process your markdown files on every request, which is fine for development but can slow down larger sites.

Styling Your Content

Pyxie and FastHTML are framework-agnostic - you can use any CSS solution you prefer. For this quick start guide, we'll use Tailwind CSS with its Typography plugin as it's one of the fastest ways to get beautiful content styling.

Create static/css/input.css:

@import "tailwindcss";
/* Enable the Typography plugin for styling markdown content */
@plugin "@tailwindcss/typography";

The Typography plugin provides ready-to-use classes that will style your markdown content with:

• Beautiful typography and spacing

• Responsive font sizes

• Proper heading hierarchy

• Styled lists and blockquotes

• Code block formatting

Don't want to use Tailwind? You can:

• Write your own CSS classes

• Use any CSS framework you prefer

• Import existing design systems

• Create custom styling per layout

Creating Layouts

Now let's create a simple layout that will style our markdown content. Create layouts/default.py:

@layout("default")
def default_layout(metadata):
    """Basic blog post layout."""
    return Div(
        # Header with title - safely get from frontmatter or use default
        H1(metadata.get('title', 'Untitled'),
           cls="text-3xl font-bold"),
        # Main content slot with typography styling
        # First argument (None) is the default content if no <content> tags exist
        # The div won't render at all if the slot is empty
        Div(None, data_slot="content",
            cls="prose dark:prose-invert"),
        cls="max-w-3xl mx-auto px-4 py-8"
    )

Let's break down how this layout works:

1. Metadata Handling:

   • metadata.get('title', 'Untitled') safely retrieves the title from your frontmatter

   • If the title doesn't exist, it defaults to 'Untitled'

   • This pattern prevents errors if frontmatter fields are missing

2. Slot Behavior:

   • Div(None, data_slot="content") creates a content slot

   • The first argument (None) is what shows up if no content is provided

   • If your markdown doesn't include <content> tags, the div won't appear in the final HTML

   • This helps prevent empty containers in your output

The prose class will style your markdown content if you're using Tailwind Typography.

Writing Content

With our styling and layout ready, let's create our first post. Create posts/hello.md:

---
title: "Hello, Pyxie!"
date: 2024-03-20
status: published
---
<content>
# Welcome to My Site
This is my first Pyxie post! The content inside this XML-style block
will be inserted into our layout's content slot and styled automatically.
You can write regular markdown here:
- Lists
- **Bold text**
- *Italic text*
- [Links](/somewhere)
<!-- Mix in some HTML if you want -->
<div class="custom-class">HTML works too!</div>
<!-- Use FastHTML for dynamic content -->
<fasthtml>
# Import components from your app
from components import Button
from datetime import datetime
def Greeting():
    return Div(
        H1("Hello, World!", cls="text-3xl font-bold"),
        P(f"The time is: {datetime.now().strftime('%H:%M')}"),
        Button(text="Click me!", onclick="alert('Hello!')")
    )
# Use show() to render FastHTML components
show(Greeting())
</fasthtml>
Back to regular markdown content...
</content>

Let's break down what's happening in this post:

1. Content Flexibility:

   • Write regular markdown anywhere

   • Mix in HTML when needed

   • Use <fasthtml> blocks for dynamic Python-powered content

2. FastHTML Blocks:

   • Wrap Python code in <fasthtml> tags

   • Import components from anywhere in your app

   • Define new components inline

   • Use any Python functionality you need

3. The show() Function:

   • Use show() to render FastHTML components in your content

   • Can show single components or multiple at once

   • Perfect for dynamic content, interactive elements, or complex layouts

   • Components are rendered in place where show() is called

This flexibility means you can:

• Keep simple content in clean markdown

• Add HTML wherever you want

• Use FastHTML when you need dynamic features

• Import and reuse components across your site