Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 61 ยท Getting Started

Exploring Dawn, the Reference Theme

Clone Dawn, read theme.liquid and the main sections, see how a product page is assembled from JSON and blocks, and decide when to fork or start fresh.

Reading good code is the fastest way to learn a platform. Shopify publishes a free, open-source theme called Dawn that shows the recommended structure for Online Store 2.0: JSON templates, sections everywhere, modern JavaScript and accessible markup. Most new themes start from it, and many agencies fork it for client stores.

In this lesson you will clone Dawn, read the layout, follow how a product page is put together, and learn about newer reference themes. The theme itself is real code that you download and open in your editor, so the examples here are read-only excerpts and descriptions. Two live stand-ins show the assembly logic with made-up data. File contents change between Dawn releases, so use the structure as a guide and always read the current files in your own copy.

Get a copy

Dawn lives in a public repository under the Shopify organization on GitHub. You can clone it directly or let the CLI do it:

Terminal
git clone https://github.com/Shopify/dawn.git my-dawn
cd my-dawn
# or
shopify theme init my-dawn

Open the folder in your editor. Before reading code, run shopify theme dev --store your-store.myshopify.com (see Setting Up) so you can look at the rendered page next to the source. Use your editor's "find in files" constantly: searching for a class name in the browser's inspector and then in the code is how you trace any element to its source file.

Read the layout first: theme.liquid

Open layout/theme.liquid. The file is short enough to read in one sitting. The parts to look for, in the order they appear (shortened and simplified here, not a verbatim copy):

LIQUID
<!doctype html>
<html class="no-js" lang="{{ request.locale.iso_code }}">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <link rel="canonical" href="{{ canonical_url }}">

    <title>{{ page_title }}</title>

    {{ content_for_header }}

    {%- render 'meta-tags' -%}
    {%- render 'css-variables' -%}
    {{ 'base.css' | asset_url | stylesheet_tag }}
    <script src="{{ 'global.js' | asset_url }}" defer="defer"></script>
  </head>

  <body class="gradient">
    {%- sections 'header-group' -%}
    <main id="MainContent" class="content-for-layout focus-none" role="main" tabindex="-1">
      {{ content_for_layout }}
    </main>
    {%- sections 'footer-group' -%}
  </body>
</html>

What each piece teaches you:

  • {{ content_for_header }} is required. Shopify injects scripts here: analytics, app embeds, the theme editor's code. Removing it breaks the store.
  • render 'css-variables' is a snippet that turns the merchant's theme settings into CSS custom properties.
  • sections 'header-group' and sections 'footer-group' render section groups (JSON files in sections/) so merchants can edit header and footer sections in the editor.
  • {{ content_for_layout }} is where the page template appears, inside a main landmark.

This single file shows the whole layout idea. See Layouts and theme.liquid for the full tour.

The main sections

Every page template has a "main" section that does the core job. The naming convention in Dawn makes them easy to find:

Template Main section
product.json main-product.liquid
collection.json main-collection-banner.liquid and main-collection-product-grid.liquid
cart.json main-cart-items.liquid and main-cart-footer.liquid
page.json main-page.liquid
blog.json main-blog.liquid
article.json main-article.liquid
search.json main-search.liquid
404.json main-404.liquid

Other sections (featured-collection, image-banner, rich-text, multicolumn) are general-purpose ones the merchant can add to any page. A good habit: when you want to change a page, first find its main-* section; when you want to add a general feature, look at the generic sections.

Product, Collection, Cart and Page Templates covers each main section in detail.

How a product page is assembled

Open templates/product.json. It does not contain HTML. It lists sections, their settings and their blocks. A simplified shape (read-only; the real file contains more settings):

JSON
{
  "sections": {
    "main": {
      "type": "main-product",
      "blocks": {
        "title": { "type": "title" },
        "price": { "type": "price" },
        "variant_picker": { "type": "variant_picker", "settings": { "picker_type": "button" } },
        "buy_buttons": { "type": "buy_buttons" }
      },
      "block_order": ["title", "price", "variant_picker", "buy_buttons"],
      "settings": { "enable_sticky_info": true }
    },
    "related-products": { "type": "related-products", "settings": { "products_to_show": 4 } }
  },
  "order": ["main", "related-products"]
}

Reading it from the top: the order array says "render main, then related-products". The main entry is an instance of the file sections/main-product.liquid. Inside that file, Liquid loops over section.blocks and uses {% case block.type %} to draw each block (title, price, picker and so on). The merchant can reorder blocks in the editor, which rewrites block_order in this JSON.

Inside main-product.liquid the media gallery and price come from snippets, such as the product media gallery and price.liquid, and the buy form uses {% form 'product', product %}. Follow the references as you read; each snippet is only a few lines of focused code.

flowchart TD
  T["templates/product.json"] --> M["main-product.liquid"]
  T --> R["related-products.liquid"]
  M --> B1["title block"]
  M --> B2["price block"]
  M --> B3["variant_picker block"]
  M --> B4["buy_buttons block"]
  B2 --> SP["snippets/price.liquid"]
  R --> SC["snippets/card-product.liquid"]

The JSON template names sections; sections draw their blocks; blocks reuse snippets.

Try it: resolve a JSON template

This stand-in does what Shopify does with a JSON template at a tiny scale: it follows order, then block_order for each section, and prints the structure of the page. It is not the real engine. It only walks the data.

JS Stand-in: walk a product template

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

No output.

The output lists the main section, its four blocks in order, then the related products section.

Try it: reorder blocks like a merchant

When a merchant drags blocks in the theme editor, only block_order changes. The section's Liquid is the same. This stand-in renders a block list from a block_order, then "moves" a block, to show why the layout is data and not code.

JS Stand-in: reordering blocks changes data, not code

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

No output.

The JavaScript and CSS in Dawn

Dawn keeps JavaScript small. Look in assets/ for global.js (shared helpers, custom elements) and pubsub.js (a minimal event bus the cart and product form use to talk to each other). Features are written as web components: classes registered with customElements.define, for example the cart drawer, quantity input and variant selects. CSS files follow the component-*.css and section-*.css naming, and many are loaded only on the pages that need them to save bytes. JavaScript in Themes covers the patterns.

Newer reference themes: Horizon

Dawn shows the sections-and-blocks model of Online Store 2.0. Shopify's newer reference theme, Horizon, is built around theme blocks: reusable files in the blocks/ folder that can nest inside each other, so merchants get much more freedom to compose layouts without a developer. If you plan to build themes that use nested blocks, read Horizon next. The two coexist; plenty of stores still use Dawn-based themes, and what you learn about sections, schema and Liquid applies to both. Reference themes evolve, so check Shopify's documentation for the current recommended starting point.

Fork Dawn or start from scratch?

Option Good when Watch out for
Fork Dawn Client work with a deadline, a theme you will sell, learning You inherit its structure and must merge updates yourself
Start from scratch You need a very different structure, or want to understand everything You rebuild accessibility, performance and editor support yourself
Use a Theme Store theme and customize The merchant wants support and updates from the theme author Customizations can clash with theme updates

Most professionals fork Dawn or a similar base and delete what they do not need. Keep a note of the Dawn release you forked, so you can compare against upstream later (see Maintaining Themes: Updates and API Versions).

When reading Dawn, do not try to understand every file. Pick one feature (say, the quantity selector), search for it, follow its Liquid, CSS and JavaScript, then move on. Ten small traces teach more than one long read-through.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is {{ content_for_header }} required in theme.liquid?

    Removing it breaks features that rely on scripts Shopify injects into the head, including app embeds and the theme editor.
  2. 2. In templates/product.json, what does the order array describe?

    order lists section ids from top to bottom. Each section lists its own blocks with block_order.
  3. 3. A merchant drags the price block above the title in the theme editor. What changes?

    The section code stays the same. The editor saves the new order in the JSON template.
  4. 4. What is Horizon known for compared with Dawn?

    Horizon is a newer reference theme that makes heavy use of theme blocks in the blocks folder, giving merchants more layout freedom.

Summary

  • Dawn is Shopify's open-source reference theme; read it with your own copy running next to it.
  • theme.liquid shows the layout idea: head, header group, content_for_layout, footer group.
  • Each page type has a main-* section; JSON templates list sections and blocks as data.
  • Reordering blocks in the editor changes JSON, not Liquid.
  • Horizon builds on theme blocks; choose between forking, starting fresh or customizing a store theme based on the project.

Next, see how merchants use your work in The Theme Editor and How Merchants Use Your Theme.