@spree/docs 0.1.0 → 0.1.2

package/dist/developer/tutorial/seo.md

@@ -1,332 +0,0 @@
----
-title: SEO
-description: Learn how to optimize your Brands feature for search engines
----
-
-> **INFO:** This guide assumes you've completed the [Storefront](/developer/tutorial/storefront) tutorial. You should have working brand pages.
-
-This guide covers SEO best practices for your custom Spree features, including friendly URLs, meta tags, and Open Graph data.
-
-## SEO-Friendly URLs
-
-Rather than using database IDs in URLs:
-
-```
-https://example.com/brands/1
-```
-
-Create human-readable URLs that help with SEO:
-
-```
-https://example.com/brands/nike-sportswear
-```
-
-### Step 1: Add SEO Columns
-
-Add columns for slug and meta fields:
-
-```bash
-bin/rails g migration AddSeoFieldsToSpreeBrands slug:string:uniq meta_title:string meta_description:text
-```
-
-```bash
-bin/rails db:migrate
-```
-
-This adds:
-- `slug` - SEO-friendly URL with unique index
-- `meta_title` - Custom page title for search engines
-- `meta_description` - Description shown in search results
-
-### Step 2: Add FriendlyId to the Model
-
-Add FriendlyId to generate SEO-friendly URLs automatically:
-
-```ruby app/models/spree/brand.rb {3-4,9}
-module Spree
-  class Brand < Spree::Base
-    extend FriendlyId
-    friendly_id :slug_candidates, use: %i[slugged]
-
-    # ... other code ...
-
-    validates :name, presence: true
-    validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-  end
-end
-```
-
-The `slug_candidates` method is already defined in `Spree::Base`:
-
-```ruby
-def slug_candidates
-  [
-    :name,
-    [:name, :uuid_for_friendly_id]
-  ]
-end
-```
-
-This generates the slug from the name. If the name is taken, it appends a UUID.
-
-### Step 3: Add SEO Fields to Admin
-
-Spree provides a reusable SEO partial that handles slug, meta title, and meta description with a live search preview. Update your admin form:
-
-```erb app/views/spree/admin/brands/_form.html.erb {1-2,5-12,15,25-32}
-<div class="row" data-controller="slug-form seo-form">
-  <div class="col-lg-8">
-    <div class="card mb-6">
-      <div class="card-body">
-        <%= f.spree_text_field :name,
-            required: true,
-            data: {
-              seo_form_target: 'sourceTitleInput',
-              slug_form_target: 'name',
-              action: 'slug-form#updateUrlFromName'
-            } %>
-        <%= f.spree_rich_text_area :description,
-            data: { seo_form_target: 'sourceDescriptionInput' } %>
-      </div>
-    </div>
-  </div>
-
-  <div class="col-lg-4">
-    <div class="card mb-6">
-      <div class="card-header">
-        <h5 class="card-title"><%= Spree.t(:logo) %></h5>
-      </div>
-      <div class="card-body">
-        <%= f.spree_file_field :logo, width: 300, height: 300, crop: true %>
-      </div>
-    </div>
-
-    <%= render 'spree/admin/shared/seo',
-          f: f,
-          title: @brand.name,
-          meta_title: @brand.meta_title,
-          description: @brand.description,
-          slug: @brand.slug,
-          slug_path: 'brands',
-          placeholder: 'Add a name and description to see how this brand might appear in a search engine listing' %>
-  </div>
-</div>
-```
-
-The SEO partial provides:
-- **Live preview** of how the page will appear in search results
-- **Meta title** field with character count
-- **Meta description** field
-- **Slug** field with auto-generation from name
-
-The `seo-form` Stimulus controller syncs the preview with your form inputs in real-time.
-
-Don't forget to permit the SEO attributes in your controller:
-
-```ruby app/controllers/spree/admin/brands_controller.rb {6-8}
-def permitted_resource_params
-  params.require(:brand).permit(
-    :name,
-    :description,
-    :logo,
-    :slug,
-    :meta_title,
-    :meta_description)
-end
-```
-
-### Step 4: Use Slugs in Storefront
-
-Update your controller to use `friendly.find`:
-
-```ruby app/controllers/spree/brands_controller.rb
-def load_brand
-  @brand = Spree::Brand.friendly.find(params[:id])
-end
-```
-
-The `friendly.find` method:
-- Finds by slug first (e.g., `/brands/nike-sportswear`)
-- Falls back to ID if no slug matches
-- Raises `ActiveRecord::RecordNotFound` if neither is found
-
-### URL Helpers
-
-Always pass the model object to path helpers:
-
-```erb
-<%= link_to brand.name, spree.brand_path(brand) %>
-<%# => /brands/nike-sportswear %>
-```
-
-FriendlyId overrides `to_param` to return the slug automatically.
-
-### Handling Slug Changes
-
-To redirect old URLs when slugs change, enable slug history:
-
-```ruby app/models/spree/brand.rb
-extend FriendlyId
-friendly_id :slug_candidates, use: %i[slugged history]
-```
-
-Old slugs will automatically resolve to the current slug.
-
-## Meta Tags & Open Graph
-
-Spree automatically generates meta tags and Open Graph data. The system uses a helper called `object` that finds the main instance variable based on your controller name.
-
-For `BrandsController`, Spree looks for `@brand` and generates:
-- Meta description
-- Open Graph tags (og:title, og:description, og:image)
-- Twitter Card tags
-
-### Page Title
-
-Override `accurate_title` in your controller to set the page `<title>`:
-
-```ruby app/controllers/spree/brands_controller.rb
-private
-
-def accurate_title
-  if @brand
-    @brand.meta_title.presence || @brand.name
-  else
-    Spree.t(:brands)
-  end
-end
-```
-
-### Meta Description
-
-Spree checks these sources in order:
-
-1. `@page_description` instance variable (if set)
-2. `@brand.meta_description` (if the model has this attribute)
-3. `current_store.meta_description` (fallback)
-
-#### Using the SEO Partial
-
-If you followed [Step 1](#step-1-add-seo-columns) and [Step 3](#step-3-add-seo-fields-to-admin), your model already has `meta_description` and the admin form uses the SEO partial. Spree will automatically use `@brand.meta_description` for the page description.
-
-#### Manual Override
-
-For custom logic, set `@page_description` directly:
-
-```ruby
-def show
-  @page_description = "Shop #{@brand.name} - #{@brand.products.count} products available"
-end
-```
-
-### Social Sharing Image
-
-For Open Graph images, Spree checks:
-
-1. `@page_image` instance variable (if set)
-2. `@brand.image` (if the model responds to `image`)
-3. `current_store.social_image` (fallback)
-
-If your Brand model has `logo` but not `image`, add an alias:
-
-```ruby app/models/spree/brand.rb
-def image
-  logo
-end
-```
-
-Or set it manually:
-
-```ruby
-def show
-  @page_image = @brand.logo if @brand.logo.attached?
-end
-```
-
-## Complete SEO-Optimized Model
-
-Here's a complete Brand model with full SEO support:
-
-```ruby app/models/spree/brand.rb
-module Spree
-  class Brand < Spree::Base
-    extend FriendlyId
-    friendly_id :slug_candidates, use: %i[slugged]
-
-    has_many :products, class_name: 'Spree::Product', dependent: :nullify
-
-    has_one_attached :logo
-    has_rich_text :description
-
-    # Database columns: slug, meta_title, meta_description
-
-    validates :name, presence: true
-    validates :slug, presence: true, uniqueness: { scope: spree_base_uniqueness_scope }
-
-    # SEO: Use logo as Open Graph image
-    def image
-      logo
-    end
-  end
-end
-```
-
-## Complete SEO-Optimized Controller
-
-```ruby app/controllers/spree/brands_controller.rb
-module Spree
-  class BrandsController < StoreController
-    before_action :load_brand, only: [:show]
-
-    def index
-      @brands = Spree::Brand.order(:name)
-    end
-
-    def show
-      @products = @brand.products
-                        .active(current_currency)
-                        .includes(storefront_products_includes)
-                        .page(params[:page])
-                        .per(12)
-
-      # Optional: Custom page description
-      # @page_description = "Shop #{@brand.name} products"
-
-      # Optional: Custom social image
-      # @page_image = @brand.logo if @brand.logo.attached?
-    end
-
-    private
-
-    def load_brand
-      @brand = Spree::Brand.friendly.find(params[:id])
-    end
-
-    def accurate_title
-      if @brand
-        @brand.meta_title.presence || @brand.name
-      else
-        Spree.t(:brands)
-      end
-    end
-  end
-end
-```
-
-## SEO Checklist
-
-**Friendly URLs** - Use slugs instead of IDs (`/brands/nike` not `/brands/1`)
-
-**Page Titles** - Override `accurate_title` for descriptive titles
-
-**Meta Descriptions** - Add `meta_description` field or set `@page_description`
-
-**Social Images** - Provide `image` method or set `@page_image` for Open Graph
-
-**Slug History** - Enable FriendlyId history to handle URL changes gracefully
-
-## Related Documentation
-
-- [Storefront Tutorial](/developer/tutorial/storefront) - Building storefront pages
-- [Model Tutorial](/developer/tutorial/model) - Creating the Brand model
-- [Admin Tutorial](/developer/tutorial/admin) - Building the admin interface

package/dist/developer/tutorial/storefront.md

@@ -1,352 +0,0 @@
----
-title: Storefront
-description: Learn how to create storefront pages for your Brands feature
----
-
-In this tutorial, we'll create storefront pages to display brands to your customers. We'll start with a simple Rails approach using controllers and views, then in the next guide we'll connect it to Page Builder.
-
-> **INFO:** This guide assumes you've completed the [Model](/developer/tutorial/model), [Admin](/developer/tutorial/admin), [Rich Text](/developer/tutorial/rich-text), [File Uploads](/developer/tutorial/file-uploads), and [Extending Core Models](/developer/tutorial/extending-models) tutorials. You should have a working `Spree::Brand` model with products associated to brands.
-
-## What We're Building
-
-By the end of this tutorial, you'll have:
-
-- A custom theme for your store
-- A brands listing page at `/brands`
-- Individual brand pages at `/brands/:id`
-- Styled views using Tailwind CSS
-
-## Step 1: Create a Custom Theme
-
-Before adding custom views, create your own theme. This is important because:
-
-- **Upgrade safety** - Your customizations won't be overwritten when updating Spree
-- **Clean separation** - Your code stays separate from Spree's default theme
-- **Full control** - You get a complete copy of all templates to customize
-
-Run the theme generator:
-
-```bash
-bin/rails g spree:storefront:theme MyStore
-```
-
-This creates:
-- `app/views/themes/my_store/` - Copy of all storefront templates
-- `app/models/spree/themes/my_store.rb` - Theme configuration class
-
-The generator also updates your `config/initializers/spree.rb`:
-
-```ruby config/initializers/spree.rb
-Spree.page_builder.themes << Spree::Themes::MyStore
-```
-
-### Activate Your Theme
-
-1. Go to **Admin → Storefront → Themes**
-2. Find your new theme in the "Add new theme" section
-3. Click **Add** to activate it
-
-> **WARNING:** Always create a custom theme for production stores. Never modify the default theme directly - your changes will be lost during Spree upgrades.
-
-## Step 2: Add Routes
-
-Now let's add routes for our brand pages. Create or update your routes file:
-
-```ruby config/routes.rb
-Spree::Core::Engine.add_routes do
-  scope '(:locale)', locale: /#{Spree.available_locales.join('|')}/, defaults: { locale: nil } do
-    resources :brands, only: [:index, :show]
-  end
-end
-```
-
-> **INFO:** The `scope '(:locale)'` wrapper enables internationalization - URLs like `/fr/brands` will work automatically if you have French locale enabled.
-
-## Step 3: Create the Controller
-
-Create a controller that inherits from `Spree::StoreController`. This base controller provides:
-
-- Access to `current_store`, `current_theme`, `current_currency`
-- User authentication helpers
-- Storefront layout and helpers
-- SEO and meta tag support
-
-```ruby app/controllers/spree/brands_controller.rb
-module Spree
-  class BrandsController < StoreController
-    before_action :load_brand, only: [:show]
-
-    def index
-      @brands = Spree::Brand.order(:name)
-    end
-
-    def show
-      @products = @brand.products.active(current_currency).includes(storefront_products_includes)
-    end
-
-    private
-
-    def load_brand
-      @brand = Spree::Brand.find(params[:id])
-    end
-
-    # Override to set page title for SEO
-    def accurate_title
-      if @brand
-        @brand.name
-      else
-        Spree.t(:brands)
-      end
-    end
-  end
-end
-```
-
-### Key Points
-
-- **Inherit from `Spree::StoreController`** - Not `ApplicationController`. This gives you access to all storefront functionality.
-- **Use `current_store`** - Always scope queries to the current store for multi-store support.
-- **Override `accurate_title`** - This sets the page `<title>` tag.
-
-> **TIP:** Want SEO-friendly URLs like `/brands/nike` instead of `/brands/123`? See the [SEO](/developer/tutorial/seo) tutorial to add slug support.
-
-## Step 4: Create the Views
-
-Storefront views live in your theme directory. Create the brands views in your custom theme:
-
-```bash
-mkdir -p app/views/themes/my_store/spree/brands
-```
-
-Your theme's view structure:
-
-```
-app/views/themes/my_store/spree/brands/
-├── index.html.erb
-├── show.html.erb
-└── _brand_card.html.erb
-```
-
-### Brands Listing Page
-
-```erb app/views/themes/my_store/spree/brands/index.html.erb
-<div class="page-container py-8">
-  <h1 class="text-2xl lg:text-3xl font-medium mb-8">
-    <%= Spree.t(:brands) %>
-  </h1>
-
-  <% if @brands.any? %>
-    <div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
-      <% @brands.each do |brand| %>
-        <%= render 'brand_card', brand: brand %>
-      <% end %>
-    </div>
-  <% else %>
-    <p class="text-neutral-600">
-      <%= Spree.t(:no_brands_found) %>
-    </p>
-  <% end %>
-</div>
-```
-
-### Brand Card Partial
-
-```erb app/views/themes/my_store/spree/brands/_brand_card.html.erb
-<%= link_to spree.brand_path(brand),
-    class: 'block group',
-    data: { turbo_frame: '_top' } do %>
-  <div class="aspect-square bg-accent rounded-lg overflow-hidden mb-3">
-    <% if brand.logo.attached? %>
-      <%= spree_image_tag brand.logo,
-          width: 300,
-          height: 300,
-          class: 'w-full h-full object-contain p-6 group-hover:scale-105 transition-transform',
-          alt: brand.name %>
-    <% else %>
-      <div class="w-full h-full flex items-center justify-center">
-        <span class="text-4xl font-medium text-neutral-400">
-          <%= brand.name.first.upcase %>
-        </span>
-      </div>
-    <% end %>
-  </div>
-  <h2 class="font-medium group-hover:text-primary transition-colors">
-    <%= brand.name %>
-  </h2>
-<% end %>
-```
-
-### Single Brand Page
-
-```erb app/views/themes/my_store/spree/brands/show.html.erb
-<div class="page-container py-8">
-  <%# Brand Header %>
-  <div class="flex flex-col md:flex-row gap-8 mb-12">
-    <% if @brand.logo.attached? %>
-      <div class="w-32 h-32 bg-accent rounded-lg flex-shrink-0">
-        <%= spree_image_tag @brand.logo,
-            width: 128,
-            height: 128,
-            class: 'w-full h-full object-contain p-4',
-            alt: @brand.name %>
-      </div>
-    <% end %>
-
-    <div>
-      <h1 class="text-2xl lg:text-3xl font-medium mb-4">
-        <%= @brand.name %>
-      </h1>
-
-      <% if @brand.description.present? %>
-        <div class="prose max-w-none text-neutral-600">
-          <%= @brand.description %>
-        </div>
-      <% end %>
-    </div>
-  </div>
-
-  <%# Products Grid %>
-  <% if @products.any? %>
-    <h2 class="text-xl font-medium mb-6">
-      <%= Spree.t(:products_by_brand, brand: @brand.name) %>
-    </h2>
-
-    <div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
-      <%= render 'spree/shared/products', products: @products %>
-    </div>
-  <% else %>
-    <p class="text-neutral-600">
-      <%= Spree.t(:no_products_found) %>
-    </p>
-  <% end %>
-</div>
-```
-
-## Step 5: Add Translations
-
-Add the necessary translations:
-
-```yaml config/locales/en.yml
-en:
-  spree:
-    brands: Brands
-    no_brands_found: No brands found.
-    products_by_brand: "Products by %{brand}"
-```
-
-## Step 6: Add Navigation Link (Optional)
-
-To add a link to brands in your header navigation, you can use the Admin Dashboard:
-
-1. Go to **Storefront → Theme Editor**
-2. Click on **Header** section
-3. Add a new navigation link pointing to `/brands`
-
-Or programmatically in your header partial:
-
-```erb
-<%= link_to Spree.t(:brands), spree.brands_path, class: 'nav-link' %>
-```
-
-## Understanding the View Structure
-
-### Theme Directory
-
-Views are organized by theme in `app/views/themes/{theme_name}/spree/`:
-
-```
-app/views/themes/my_store/spree/
-├── brands/           # Your brand views
-├── products/         # Product views
-├── shared/           # Shared partials
-└── page_sections/    # Page Builder sections
-```
-
-> **INFO:** Spree looks for views in your active theme first. If a view isn't found, it falls back to the default theme. This means you only need to copy and customize the files you want to change.
-
-### Key CSS Classes
-
-Spree's default theme uses these common patterns:
-
-| Class | Purpose |
-|-------|---------|
-| `page-container` | Centered container with max-width and padding |
-| `bg-accent` | Uses theme's accent background color |
-| `text-primary` | Uses theme's primary text color |
-| `btn-primary` | Primary button style |
-| `btn-secondary` | Secondary button style |
-
-### Using Spree Helpers
-
-```erb
-<%# Image helper with automatic optimization %>
-<%= spree_image_tag image, width: 400, height: 400 %>
-
-<%# URL helpers %>
-<%= spree.brands_path %>
-<%= spree.brand_path(brand) %>
-
-<%# Translation helper %>
-<%= Spree.t(:brands) %>
-
-<%# Price display %>
-<%= display_price(product.price_in(current_currency)) %>
-```
-
-## Testing Your Pages
-
-Start your Rails server and visit:
-
-- `http://localhost:3000/brands` - Brand listing
-- `http://localhost:3000/brands/1` - Single brand (using the brand's ID)
-
-> **TIP:** Want SEO-friendly URLs like `/brands/nike` instead of `/brands/1`? See the [SEO](/developer/tutorial/seo) tutorial to add slug support, meta tags, and Open Graph data.
-
-## What's Next?
-
-You now have working brand pages using standard Rails MVC patterns. In the next guide, [Testing](/developer/tutorial/testing), we'll write automated tests for your feature to make sure it works as expected, also in the future when you make changes to your code.
-
-## Complete Controller Example
-
-Here's the complete controller with all features:
-
-```ruby app/controllers/spree/brands_controller.rb
-module Spree
-  class BrandsController < StoreController
-    before_action :load_brand, only: [:show]
-
-    def index
-      @brands = Spree::Brand.order(:name)
-                            .page(params[:page])
-                            .per(24)
-    end
-
-    def show
-      @products = @brand.products.active(current_currency).includes(storefront_products_includes)
-      @page_description = @brand.description&.to_plain_text&.truncate(160)
-    end
-
-    private
-
-    def load_brand
-      @brand = Spree::Brand.find(params[:id])
-    end
-
-    def accurate_title
-      if @brand
-        @brand.name
-      else
-        Spree.t(:brands)
-      end
-    end
-  end
-end
-```
-
-> **INFO:** To use SEO-friendly slugs like `/brands/nike` instead of `/brands/1`, follow the [SEO](/developer/tutorial/seo) tutorial.
-
-## Related Documentation
-
-- [Storefront Overview](/developer/storefront/storefront) - Storefront architecture
-- [Custom CSS](/developer/storefront/custom-css) - Styling with Tailwind
-- [Helper Methods](/developer/storefront/helper-methods) - Available helpers