wordpress-sage-theme

WordPress Sage Theme Development

Overview

Sage is a WordPress theme framework by Roots that provides modern development practices including Blade templates, dependency management with Composer, and build tools with Vite/Bud.

When to Use

• Creating new Sage themes from scratch or from composer templates
• Setting up Blade templates, layouts, and reusable components
• Configuring build tools (Bud/Vite) for asset compilation
• Working with WordPress template hierarchy in Blade format
• Integrating Advanced Custom Fields (ACF) with Blade templates
• Debugging theme rendering, asset loading, or build issues

Instructions

1. Set up the environment: Install PHP 8.0+, Node.js 18+, Composer, and create a new Sage theme with composer create-project roots/sage
2. Configure build tools: Run npm install && composer install, then configure bud.config.js for asset entries and Tailwind
3. Create Blade templates: Place templates in resources/views/, using layouts in layouts/, components in components/
4. Wire up WordPress templates: Map WordPress template hierarchy to Blade files (e.g., page.blade.php for page templates)
5. Integrate ACF fields: Use get_field() for basic fields, have_rows() loops for repeaters and flexible content
6. Build and verify: Run npm run build, verify public/manifest.json exists, check browser console for asset errors
7. Deploy: Ensure the production build step (npm run build) runs during deployment; raw source files cannot be served directly

Examples

Create a new Sage theme:

composer create-project roots/sage my-theme
cd my-theme
npm install && composer install
npm run dev

Blade page template:

@extends('layouts.app')

@section('content')
  <main class="content">
    <h1>{{ the_title() }}</h1>
    <div class="entry-content">
      {{ the_content() }}
    </div>
  </main>
@endsection

ACF flexible content in Blade:

@if (have_rows('flexible_content'))
  @while (have_rows('flexible_content'))
    @php the_row() @endphp
    @switch(get_row_layout())
      @case('hero_section')
        @include('components.hero')
        @break
    @endswitch
  @endwhile
@endif