Theme Development
Oizzy themes are built with Liquid templating and a pattern-based section system. This guide covers everything you need to build a custom theme.
Theme Structure
Every theme lives in its own directory with the following structure:
themes/your-theme/
theme.json # Theme config: name, version, settings, patterns, parts
layouts/
default.liquid # Main layout template
templates/
index.liquid # Homepage template
post.liquid # Single post template
page.liquid # Single page template
error.liquid # Error page template
patterns/ # Section pattern partials
hero-banner.liquid
post-archive.liquid
cta-section.liquid
...
partials/ # Shared partials (post cards, etc.)
post-card.liquid
...
styles/ # Style variation JSON files
default.json
dark.json
...
assets/ # Theme-specific static assets
logo.svg
...
theme.json
The theme.json file defines your theme's metadata, available patterns, settings, and style variations. It tells Oizzy's design editor what sections are available and how they can be configured.
Layouts
Layout files wrap your templates. The default.liquid layout typically includes the {% oizzy_head %}, {% oizzy_styles %}, and {% oizzy_foot %} tags to inject required meta tags, stylesheets, and scripts.
Templates
Templates define the structure of each page type. They use the {% sections %} tag to render the design editor's section layout, or {% pattern %} to render individual patterns.
Patterns
Patterns are the building blocks of your theme's design. Each pattern is a Liquid partial that renders a configurable section. The design editor lets users add, remove, and reorder patterns on any page.
Partials
Shared Liquid partials used across multiple patterns or templates (e.g., a post card component used in both post-archive and featured-post).
Styles
JSON files defining style variations (color schemes, typography presets). Users can switch between styles in the design editor.
Assets
Static files specific to your theme (images, icons, fonts).
Pattern System
Oizzy uses a tiered pattern system to ensure consistency across themes while allowing creative freedom.
| Tier | Meaning | Enforcement |
|---|---|---|
| Tier 1: Required | Every general theme MUST implement these. Without them, the theme is incomplete. | Hard requirement |
| Tier 2: Recommended | Themes SHOULD implement these. A theme missing all of them feels bare. | Soft requirement |
| Tier 3: Theme-Specific | Creative freedom. Themes can add any patterns that serve their niche. | Optional |
Tier 1: Required Patterns
Every general theme must implement all of the following.
hero-* (at least one variant)
First impression, above-the-fold section. Themes may name their hero variants freely (e.g. hero-banner, hero-split, hero-minimal) as long as at least one exists.
No standard fields enforced — hero sections are highly theme-specific.
post-archive
Grid or list of posts with filtering, sorting, and count controls.
| Field | Type | Description |
|---|---|---|
heading | text | Section title |
post_count | select: 3, 6, 9, 12, all | How many posts to show |
collection | select | Filter by collection |
sort_by | select: published_at_desc, published_at_asc, title_asc, title_desc | Sort order |
show_feature_image | toggle (default: true) | Show post feature images |
show_excerpt | toggle (default: true) | Show post excerpts |
show_date | toggle (default: true) | Show publish dates |
All themes must use the name post-archive.
cta-section
Call-to-action block with heading, description, and button.
| Field | Type | Description |
|---|---|---|
heading | text | CTA heading |
subheading | textarea | Supporting description |
button_text | text | Button label |
button_url | url | Button link target |
style | select: default, accent, minimal | Visual style variant |
rich-text
Freeform content block for arbitrary text content outside of posts/pages.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
body | textarea | Rich text content |
alignment | select: left, center | Text alignment |
post-header
Single post view: title, date, tags. No standard fields — rendered from post data via Liquid drops.
post-feature-image
Single post view: hero/feature image. No standard fields — rendered from post data via Liquid drops.
post-content
Single post view: body content. No standard fields — rendered from post data via Liquid drops.
post-author
Single post view: author byline with name and optional avatar. No standard fields — rendered from post data via Liquid drops.
page-header
Single page view: title. No standard fields — rendered from page data via Liquid drops.
page-feature-image
Single page view: hero/feature image. No standard fields — rendered from page data via Liquid drops.
page-content
Single page view: body content. No standard fields — rendered from page data via Liquid drops.
Tier 2: Recommended Patterns
Themes should implement these to add depth. A theme missing all of them feels bare.
about-section
Bio or description block with optional image. Useful for author intros, company descriptions, or mission statements.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
body | textarea | Bio or description text |
image | image | Optional photo or illustration |
alignment | select: left, center, right | Layout alignment (image position) |
newsletter-signup
Email capture section for building an audience. This is a UI-only pattern — backend email collection will integrate with a mailer/list provider in a future iteration.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading (e.g. "Stay updated") |
subheading | textarea | Supporting description |
button_text | text | Submit button label (e.g. "Subscribe") |
placeholder_text | text | Input placeholder (e.g. "[email protected]") |
featured-post
Single highlighted post displayed larger or more prominently than archive cards. Useful for pinning important content.
| Field | Type | Description |
|---|---|---|
heading | text | Optional section heading |
post | post-select | The featured post to display |
show_excerpt | toggle (default: true) | Show post excerpt |
show_date | toggle (default: true) | Show publish date |
image-gallery
Grid of images, optionally clickable or expandable.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
columns | select: 2, 3, 4 | Grid column count |
items | repeater | List of gallery items |
items.image | image | Gallery image |
items.caption | text | Optional caption |
items.url | url | Optional link |
testimonials
Quotes, reviews, or endorsements.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
items | repeater | List of testimonials |
items.quote | textarea | The testimonial text |
items.name | text | Attribution name |
items.title | text | Attribution title/role |
items.image | image | Optional avatar |
social-proof
Logos bar showing media mentions, client logos, or partner brands.
| Field | Type | Description |
|---|---|---|
heading | text | Optional heading (e.g. "As seen in") |
items | repeater | List of logos |
items.image | image | Logo image |
items.name | text | Organization name (alt text) |
items.url | url | Optional link |
divider
Visual separator between sections.
| Field | Type | Description |
|---|---|---|
style | select: line, space, dots | Divider style |
spacing | select: small, medium, large | Vertical spacing |
Tier 3: Theme-Specific Patterns
Themes can add any patterns that serve their niche. Here are some examples:
| Pattern | Purpose |
|---|---|
faq-accordion | Expandable Q&A sections |
podcast-embed | Audio player with episode info |
stats-bar | Key numbers/metrics display |
timeline | Chronological events |
post-list | Alternative minimal post feed |
services-columns | Service offerings grid |
photo-scroll | Horizontal scrolling gallery |
Example: faq-accordion
Expandable Q&A sections using <details>/<summary> HTML elements.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
items | repeater | List of Q&A pairs |
items.question | text | The question |
items.answer | textarea | The answer |
Example: podcast-embed
Audio player with episode info and platform links.
| Field | Type | Description |
|---|---|---|
heading | text | Section heading |
description | textarea | Show description |
embed_url | text | Embed URL (Spotify, Apple, YouTube) |
items | repeater | Platform links |
items.platform_name | text | Platform name (e.g. "Spotify") |
items.platform_url | url | Platform URL |
Naming Conventions
- Use kebab-case for all pattern names:
post-archive,cta-section,rich-text. - Post/page patterns use the prefix
post-orpage-followed by the content area:post-header,post-content,page-feature-image. - Section patterns are named by their function:
cta-section,about-section,newsletter-signup. - Hero patterns must start with
hero-:hero-banner,hero-split,hero-minimal. - No theme-specific naming for Tier 1 patterns. All themes use the same names to ensure consistency in
theme.jsonand the design editor. - Tier 2 and Tier 3 patterns may use theme-specific names only if they serve a meaningfully different purpose than the standard.