Skip to main content

Theme Development - Getting Started

Welcome to O2VEND theme development! This guide will help you create your first theme.

Overview​

O2VEND themes are built using Liquid templates, similar to Shopify themes. Themes consist of:

  • Templates: Page layouts (index, product, collection, etc.)
  • Sections: Reusable page sections (header, footer, hero, etc.)
  • Snippets: Reusable components (product cards, breadcrumbs, etc.)
  • Widgets: Dynamic content blocks
  • Assets: CSS, JavaScript, and images

Theme Architecture​

The following diagram illustrates the structure and relationships within an O2VEND theme:

graph TB
    Layout[theme.liquid<br/>Main Layout] --> Templates[Templates<br/>Page Types]
    Layout --> Sections[Sections<br/>Reusable Blocks]
    Layout --> Assets[Assets<br/>CSS/JS/Images]
    Templates --> Snippets[Snippets<br/>Components]
    Sections --> Snippets
    Sections --> Widgets[Widgets<br/>Dynamic Content]
    Templates --> Widgets
    Config[config/<br/>Settings] --> Layout
    Config --> Sections
    Config --> Templates

Theme Development Workflow​

flowchart TD
    Start[Start Theme Development] --> Plan[Plan Theme Structure]
    Plan --> Create[Create Theme Directory]
    Create --> Layout[Create Main Layout]
    Layout --> Templates[Create Templates]
    Templates --> Sections[Create Sections]
    Sections --> Snippets[Create Snippets]
    Snippets --> Assets[Add Assets]
    Assets --> Config[Configure Settings]
    Config --> Test[Test Locally]
    Test --> Deploy{Deploy?}
    Deploy -->|Yes| Publish[Publish Theme]
    Deploy -->|No| Refine[Refine & Iterate]
    Refine --> Test
    Publish --> End[Theme Live]

Prerequisites Checklist​

Before you begin, ensure you have:

  • Basic knowledge of HTML, CSS, and JavaScript
  • Familiarity with Liquid template syntax (or willingness to learn)
  • Access to O2VEND storefront
  • Code editor (VS Code, Sublime Text, etc.)
  • Understanding of responsive design principles
  • Basic knowledge of version control (Git)

For the best development experience, we recommend using:

O2VEND Theme CLI​

The O2VEND Theme CLI provides a complete local development environment:

  • Local development server with hot reload
  • Mock API server for offline development
  • Theme validation and optimization tools
  • Theme packaging for marketplace submission

Installation:

npm install -g @o2vend/theme-cli

Quick Start:

# Initialize a new theme
o2vend init my-theme

# Start development server
o2vend serve

Learn more: O2VEND Theme CLI Documentation

O2VEND Liquid VS Code Extension​

The O2VEND Liquid VS Code Extension enhances your editing experience:

  • Syntax highlighting for Liquid templates
  • IntelliSense and auto-completion
  • Code snippets for common patterns
  • JSON schema validation for theme configuration

Installation:

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "O2VEND Liquid"
  4. Click Install

Learn more: VS Code Extension Documentation

Quick Start​

Create your first theme in 5 minutes:

The easiest way to get started is using the O2VEND Theme CLI:

# Install CLI (if not already installed)
npm install -g @o2vend/theme-cli

# Initialize a new theme
o2vend init my-theme

# Navigate to theme directory
cd my-theme

# Start development server
o2vend serve

The CLI will:

  • Create a complete theme structure
  • Set up configuration files
  • Start a local development server with hot reload
  • Open your browser automatically

Option 2: Manual Setup​

If you prefer to create the theme structure manually:

Step 1: Create Theme Structure​

mkdir my-theme
cd my-theme
mkdir -p layout templates sections snippets assets config

Step 2: Create Main Layout​

Create layout/theme.liquid:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ page_title | default: shop.name }}</title>
  {{ 'theme.css' | asset_url | stylesheet_tag }}
</head>
<body>
  {% section 'header' %}
  <main>{{ content }}</main>
  {% section 'footer' %}
  {{ 'theme.js' | asset_url | script_tag }}
</body>
</html>

Step 3: Create Home Page Template​

Create templates/index.liquid:

{% layout 'theme' %}

<h1>Welcome to {{ shop.name }}</h1>
<p>{{ shop.description }}</p>

{% section 'hero' %}
{% section 'content' %}

Step 4: Add Basic Styles​

Create assets/theme.css:

body {
  font-family: system-ui, -apple-system, sans-serif;
  margin: 0;
  padding: 0;
}

main {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

Step 5: Configure Theme​

Create config/settings_schema.json:

{
  "name": "My Theme",
  "settings": [
    {
      "type": "text",
      "id": "theme_color",
      "label": "Theme Color",
      "default": "#000000"
    }
  ]
}

Your theme is now ready! See the Create First Theme tutorial for a complete walkthrough.

Common Mistakes to Avoid​

1. Missing Layout Declaration​

❌ Wrong:

<!-- templates/index.liquid -->
<h1>Home Page</h1>

✅ Correct:

{% layout 'theme' %}
<h1>Home Page</h1>

2. Incorrect Asset References​

❌ Wrong:

<link rel="stylesheet" href="assets/theme.css">

✅ Correct:

{{ 'theme.css' | asset_url | stylesheet_tag }}

3. Hardcoding URLs​

❌ Wrong:

<a href="/products">Products</a>

✅ Correct:

<a href="{{ 'products' | collection_url }}">Products</a>

4. Not Using Widgets for Dynamic Content​

❌ Wrong:

<div class="hero">
  <h1>Static Hero Title</h1>
</div>

✅ Correct:

{% for widget in widgets.hero %}
  {{ widget | render_widget }}
{% endfor %}

5. Missing Error Handling​

❌ Wrong:

{{ product.name }}

✅ Correct:

{% if product %}
  {{ product.name }}
{% else %}
  <p>Product not found</p>
{% endif %}

Next Steps​

Now that you understand the basics, explore these topics:

  • Liquid Templates - Learn template syntax and structure
  • Widgets - Understand dynamic content widgets
  • Snippets - Create reusable components
  • Sections - Build page sections
  • Assets - Manage CSS, JavaScript, and images
  • Filters - Use Liquid filters for data transformation