Skip to content
Tutorials Center
My learning

Topics

Lesson 42 of 61 ยท Performance and Quality

SEO in Themes

Make a Shopify theme search-friendly: titles, meta descriptions, canonical URLs, Open Graph, product JSON-LD, robots.txt.liquid, hreflang and image alt text.

Search engines read the HTML your theme produces. They do not see your design; they see a title, a description, headings, links, image alt text and structured data. Shopify does a lot of the work for you: it generates the sitemap, adds canonical tags through an object, and exposes fields in the admin where merchants write page titles and descriptions. Your job as a theme developer is to output those values correctly, keep the markup clean and avoid breaking what the platform already does.

This lesson covers the head tags a theme must print, structured data for products, social sharing tags, the editable robots.txt.liquid, URL and language considerations, and image alt text. The real theme code is read-only here (there is no Liquid engine on this site). The two live stand-ins are small JavaScript programs: one builds head tags with the same escaping and truncation rules, and one builds product JSON-LD and checks it for missing fields.

Search ranking depends on content quality, links, speed and many other things outside a theme. Treat the techniques here as a clean foundation, not a promise of position. Shopify details change over time, so confirm current behavior in your own store's page source.

The head tags every page needs

In Layouts and theme.liquid you saw that the <head> is the place for metadata. A minimal, correct SEO head looks like this (read-only Liquid, targeting Online Store 2.0 themes):

LIQUID
<title>
  {{ page_title }}
  {%- if current_tags %} &ndash; tagged "{{ current_tags | join: ', ' }}"{% endif -%}
  {%- if current_page != 1 %} &ndash; Page {{ current_page }}{% endif -%}
  {%- unless page_title contains shop.name %} &ndash; {{ shop.name }}{% endunless -%}
</title>

{%- if page_description %}
  <meta name="description" content="{{ page_description | escape }}">
{%- endif %}

<link rel="canonical" href="{{ canonical_url }}">
<meta name="viewport" content="width=device-width, initial-scale=1">

What each part does:

  • page_title is the title for the current page. For products, collections, pages and articles it comes from the merchant's "Search engine listing" fields in the admin, and falls back to the resource title. Your theme should not invent a different title.
  • page_description works the same way for the meta description. It can be empty, so wrap it in an if.
  • canonical_url is the preferred URL for the page. It matters because the same product can be reached at /products/mug and at /collections/kitchen/products/mug. Both pages show the same content; the canonical tag tells search engines which one to index.
  • The escape filter protects against quotes in the text breaking out of the attribute. See Security in Themes for why this matters beyond SEO.

Keep titles around 50 to 60 characters and descriptions around 120 to 160. Search engines may show something different, so these are goals, not rules. Pages that exist in several pages of a collection get the page number appended so titles do not repeat.

Do not add a hand-written <meta name="robots" content="noindex"> to normal pages. If you need to hide a page, use the admin's options or a deliberate rule in robots.txt.liquid, and write down why.

flowchart LR
  A["Merchant writes title<br/>and description in admin"] --> B["Liquid objects:<br/>page_title, page_description"]
  B --> C["Theme prints title, meta<br/>and Open Graph tags"]
  D["Theme resolves URL"] --> E["canonical_url"]
  E --> C
  C --> F["Crawler and social<br/>previews read the head"]

Merchant-written values flow through Liquid objects into the head; the theme only prints them safely.

Head tags are not the whole story. The visible markup matters too:

  • One <h1> per page: the product title, collection title or article title. A hero banner on the home page can carry the h1; elsewhere use h2.
  • Use real <a href> links for navigation, including pagination and filters, so crawlers can follow them. Links that only exist through JavaScript click handlers are easy to miss.
  • Use descriptive link text. "Winter tea collection" says more than "click here".
  • Keep the main content in the server-rendered HTML. Content that only appears after a script runs is slower to be understood and can be missed.

These overlap with Accessibility in Themes: good headings and link text help everyone.

Open Graph and social cards

When someone shares a link in a chat or social network, the app reads Open Graph tags to build a preview card. Themes usually put them in a snippet such as snippets/meta-tags.liquid:

LIQUID
<meta property="og:site_name" content="{{ shop.name | escape }}">
<meta property="og:url" content="{{ canonical_url }}">
<meta property="og:title" content="{{ page_title | escape }}">
<meta property="og:type" content="{% if template.name == 'product' %}product{% else %}website{% endif %}">
{%- if page_description %}
  <meta property="og:description" content="{{ page_description | escape }}">
{%- endif %}

{%- assign share_image = page_image | default: settings.share_image -%}
{%- if share_image %}
  <meta property="og:image" content="https:{{ share_image | image_url: width: 1200 }}">
  <meta property="og:image:width" content="{{ share_image.width }}">
  <meta property="og:image:height" content="{{ share_image.height }}">
{%- endif %}

<meta name="twitter:card" content="summary_large_image">

page_image is the page's own image (the product's featured image, for example) when it has one. A fallback share_image theme setting lets the merchant choose a default, which is a good use of global theme settings. Use absolute URLs with https: because preview crawlers do not resolve relative paths. Social preview sizes of about 1200 by 630 pixels work well.

Stand-in: building head tags safely

The program below imitates what the Liquid above does: it picks the title, builds the description, escapes values, truncates long text on a word boundary and chooses the Open Graph type. It runs in the browser console editor and prints the tags a crawler would see. The resource objects are made up for the demo; the logic is real JavaScript, but Shopify's own Liquid objects are what your theme uses.

JS Stand-in: build title, description and Open Graph tags

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice three behaviors worth copying in real Liquid: quotes and ampersands are escaped, a long description is cut at a word and not in the middle of one, and an empty description produces no tag instead of an empty one. The second page, "About Clay & Co", already contains the shop name, so the title is not repeated.

Structured data for products

Structured data is machine-readable information about the page, usually written as JSON-LD using the schema.org vocabulary. For products it can make search results richer: price, availability and ratings may show beside the link. Shopify's Liquid has a structured_data filter that outputs a product object in this format, and Dawn-style themes use it like this:

LIQUID
<script type="application/ld+json">
  {{ product | structured_data }}
</script>

If you build it by hand (for example to add fields), follow these rules:

  • Use the json filter for every string so quotes and line breaks are escaped. Never paste raw text into a JSON string.
  • Prices need to be a plain number with a currency code. Shopify stores prices in the smallest currency unit, so divide by 100 (for two-decimal currencies) and use cart.currency.iso_code, or localization.country.currency.iso_code for the shopper's market.
  • availability uses schema.org URLs such as https://schema.org/InStock and https://schema.org/OutOfStock.
  • Do not mark up content that is not on the page. Rating data must come from real reviews that shoppers can see.
  • Print structured data once. If an app also prints a product JSON-LD block, you end up with duplicates that can confuse validators. Check the page source after installing review apps.

A hand-written block, read-only, targeting a typical OS 2.0 product template:

LIQUID
{%- assign variant = product.selected_or_first_available_variant -%}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": {{ product.title | json }},
  "description": {{ product.description | strip_html | truncate: 300 | json }},
  "sku": {{ variant.sku | json }},
  "image": {{ product.featured_image | image_url: width: 1200 | prepend: 'https:' | json }},
  "offers": {
    "@type": "Offer",
    "url": {{ canonical_url | json }},
    "priceCurrency": {{ cart.currency.iso_code | json }},
    "price": {{ variant.price | divided_by: 100.0 | json }},
    "availability": "https://schema.org/{% if variant.available %}InStock{% else %}OutOfStock{% endif %}"
  }
}
</script>

Divide by 100.0, not 100, so Liquid does float math. Currencies with no decimal places or three decimals need different handling, which is another reason to prefer the built-in structured_data filter unless you must customize.

Stand-in: a JSON-LD builder and checker

This stand-in builds the same Product object from a mock product, then runs a checker that flags the problems search engines complain about: a missing image, a price that is not a number, an unknown availability value. The product data is invented; in a theme you read it from the product object.

JS Stand-in: product JSON-LD builder with a checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JSON.stringify does what Liquid's json filter does for you: it escapes the quotes in the product name Speckled "Dune" Mug. The checker's rules are simplified, and Google's Rich Results Test or the Schema Markup Validator remain the real authority. Run your live product page through them after launch.

Sitemap and robots.txt

  • sitemap.xml is generated by Shopify at /sitemap.xml. It lists products, collections, pages and blog posts, split into child sitemaps, and includes translated URLs for markets. You cannot edit it. Hide a product from search by changing its visibility or search settings in the admin, not by editing a file.
  • robots.txt is created by Shopify with sensible defaults (for example blocking cart and checkout paths). You can customize it with a templates/robots.txt.liquid file, which loops over Shopify's default rules so you keep them and add your own:
LIQUID
{%- for group in robots.default_groups -%}
  {{- group.user_agent -}}

  {%- for rule in group.rules -%}
    {{ rule }}
  {%- endfor -%}

  {%- if group.user_agent.value == '*' -%}
    {{ 'Disallow: /collections/*+*' }}
  {%- endif -%}

  {%- if group.sitemap != blank -%}
    {{ group.sitemap }}
  {%- endif -%}
{% endfor %}

Add rules sparingly. A wrong Disallow can remove whole sections from search results, and robots.txt blocks crawling, not indexing: a blocked page can still appear if other sites link to it. Test any change before publishing, and never use it to hide private data.

URLs, redirects and languages

  • A product's handle becomes its URL. Changing a handle in the admin can create a redirect if the box is ticked, so leave it ticked. Manage extra redirects under the store's URL redirects tool.
  • Avoid linking to duplicate paths. In a collection grid, {{ product.url | within: collection }} gives /collections/x/products/y, which is fine for breadcrumbs and "recently viewed" behavior, but the canonical tag must still point to the main product URL. Dawn does the same.
  • Keep filtered and sorted collection URLs out of the index. Filter parameters create near-duplicates; the canonical tag and the default robots rules handle most of it, so check before changing them. See Collection Pages.
  • Languages and markets. If the store sells in several languages or on several domains, search engines need to know which page serves which audience. That is the job of hreflang links. Shopify can output them for you when the store has multiple languages or domains, so look at the page source before adding your own, and never print two competing sets. Mark the page language with <html lang="{{ request.locale.iso_code }}"> as covered in Translations, Markets and Localization.

Images and alt text

Image alt text is both an SEO and an accessibility feature. It describes the image's content and purpose in a short sentence.

  • Product and article images get their alt text from the media in the admin, available as image.alt. image_tag uses it for you.
  • When alt text is empty, fall back to something meaningful, like the product title, rather than leaving the attribute out. In Liquid, compute it first: {% assign alt_text = image.alt | default: product.title %} and then {{ image | image_url: width: 800 | image_tag: alt: alt_text }}. Set alt explicitly when the image carries meaning.
  • Decorative images get alt="".
  • Do not stuff keywords. "Speckled blue stoneware mug on a wooden table" is useful; "mug mug buy mug cheap" is spam.
  • Give images width and height and use modern formats through image_url, which helps both speed and ranking signals. See Theme Performance and Core Web Vitals.

A short SEO checklist for your theme

  1. <title> from page_title, not hard-coded.
  2. Meta description wrapped in an if and escaped.
  3. canonical_url in every page head.
  4. One h1, headings in order, real links.
  5. Open Graph tags and a fallback share image setting.
  6. Product JSON-LD printed once, with correct price, currency and availability.
  7. No accidental noindex, and a tested robots.txt.liquid if you customize it.
  8. Alt text on every meaningful image.
  9. No duplicate hreflang or JSON-LD from apps.
  10. Run Lighthouse's SEO audit and the Rich Results Test before launch.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should a theme print a canonical tag using canonical_url?

    A product can be reached through its own URL and through collection-scoped URLs. The canonical tag points search engines at the version to index.
  2. 2. How should you put a product title into a hand-written JSON-LD block in Liquid?

    The json filter produces a valid JSON string and escapes quotes and line breaks, so a title like Speckled "Dune" Mug cannot break the data.
  3. 3. What does a robots.txt.liquid file let you do?

    You can customize robots rules, but sitemap.xml is generated by Shopify and cannot be edited, and robots rules control crawling, not access.
  4. 4. What is the right alt text for a purely decorative divider image?

    An empty alt tells assistive technology to skip a decorative image. Omitting alt entirely makes some screen readers read the file name.

Summary

  • Print page_title, page_description (inside an if) and canonical_url on every page, and escape values placed in attributes.
  • Add Open Graph tags with absolute https: image URLs and a fallback share image setting.
  • Use the structured_data filter, or a hand-written Product JSON-LD with the json filter, correct price, currency and availability; print it once.
  • Shopify generates sitemap.xml; customize robots.txt only through robots.txt.liquid, keeping the default groups.
  • Keep headings, links and server-rendered content clean, avoid duplicate URLs, and check hreflang before adding your own.
  • Write real alt text for meaningful images and alt="" for decorative ones.

Next, learn how to catch problems automatically in Theme Check, Linting and Testing.