shopify-liquid-themes

Shopify Liquid テーマ

テーマのアーキテクチャ

.
├── sections/    # Full-width page modules with {% schema %} — hero, product grid, testimonials
├── blocks/      # Nestable components with {% schema %} — slides, feature items, text blocks
├── snippets/    # Reusable fragments via {% render %} — buttons, icons, image helpers
├── layout/      # Page wrappers (must include {{ content_for_header }} and {{ content_for_layout }})
├── templates/   # JSON files defining which sections appear on each page type
├── config/      # Global theme settings (settings_schema.json, settings_data.json)
├── locales/     # Translation files (en.default.json, fr.json, etc.)
└── assets/      # Static CSS, JS, images (prefer {% stylesheet %}/{% javascript %} instead)

用途に応じた使い分け

必要なもの	使用するもの	理由
全幅でカスタマイズ可能なモジュール	セクション	{% schema %} を持ち、エディターに表示され、ブロックをレンダリングします
エディター設定を備えた、小さくて入れ子にできるコンポーネント	ブロック	{% schema %} を持ち、セクションやブロックの中に入れ子にできます
マーチャントが編集しない再利用可能なロジック	スニペット	スキーマを持たず、{% render %} でレンダリングし、パラメーターを受け取ります
複数のブロックやスニペットで共有するロジック	スニペット	ブロックから別のブロックを {% render %} できません

Liquid 構文

区切り文字

• {{ ... }} — 出力（値を表示します）
• {{- ... -}} — 空白を削除して出力します
• {% ... %} — ロジックタグ（if、for、assign）— 何も出力しません
• {%- ... -%} — 空白を削除するロジックタグ

演算子

比較： ==、!=、>、<、>=、<= 論理： and、or、contains

重要な注意点

1. 条件式では括弧を使用できません — 代わりに {% if %} を入れ子にします
2. 三項演算子はありません — 常に {% if cond %}value{% else %}other{% endif %} を使用します
3. for ループの最大反復回数は50回です — それより大きな配列には {% paginate %} を使用します
4. contains は文字列に対してのみ機能します — 配列内のオブジェクトは確認できません
5. {% stylesheet %}／{% javascript %} は Liquid をレンダリングしません — これらの中に Liquid を記述できません
6. スニペットから外側のスコープの変数にはアクセスできません — render パラメーターとして渡します
7. include は非推奨です — 常に {% render 'snippet_name' %} を使用します
8. {% liquid %} タグ — 区切り文字を使わずに複数行のロジックを記述できます。出力には echo を使用します

変数

{% assign my_var = 'value' %}
{% capture my_var %}computed {{ value }}{% endcapture %}
{% increment counter %}
{% decrement counter %}

フィルター早見表

フィルターは | で連結します。あるフィルターの出力型が、次のフィルターの入力になります。

配列： compact、concat、find、find_index、first、has、join、last、map、reject、reverse、size、sort、sort_natural、sum、uniq、where 文字列： append、capitalize、downcase、escape、handleize、lstrip、newline_to_br、prepend、remove、replace、rstrip、slice、split、strip、strip_html、truncate、truncatewords、upcase、url_decode、url_encode 数学： abs、at_least、at_most、ceil、divided_by、floor、minus、modulo、plus、round、times 通貨： money、money_with_currency、money_without_currency、money_without_trailing_zeros 色： color_brightness、color_darken、color_lighten、color_mix、color_modify、color_saturate、color_desaturate、color_to_hex、color_to_hsl、color_to_rgb メディア： image_url、image_tag、video_tag、external_video_tag、media_tag、model_viewer_tag URL： asset_url、asset_img_url、file_url、shopify_asset_url HTML： link_to、script_tag、stylesheet_tag、time_tag、placeholder_svg_tag ローカライズ： t（翻訳）、format_address、currency_selector その他： date、default、json、structured_data、font_face、font_url、payment_button

詳細：言語フィルター、HTML／メディアフィルター、コマースフィルター

タグ早見表

カテゴリー	タグ
テーマ	content_for、layout、section、sections、schema、stylesheet、javascript、style
制御	if、elsif、else、unless、case、when
反復処理	for、break、continue、cycle、tablerow、paginate
変数	assign、capture、increment、decrement、echo
HTML	form、render、raw、comment、liquid
ドキュメント	doc

構文とパラメーターを含む詳細：references/tags.md

オブジェクト早見表

グローバルオブジェクト（どこからでも利用可能）

cart、collections、customer、localization、pages、request、routes、settings、shop、template、theme、linklists、images、blogs、articles、all_products、metaobjects、canonical_url、content_for_header、content_for_layout、page_title、page_description、handle、current_page

ページ固有のオブジェクト

テンプレート	オブジェクト
/product	product、remote_product
/collection	collection、current_tags
/cart	cart
/article	article、blog
/blog	blog、current_tags
/page	page
/search	search
/customers/*	customer、order

詳細なリファレンス：commerce objects、content objects、tier 2、tier 3

Schema タグ

セクションとブロックでは、有効な JSON オブジェクトを含む {% schema %} が必要です。セクションでは section.settings.* を、ブロックでは block.settings.* を使用します。

セクションの schema 構造

{
  "name": "t:sections.hero.name",
  "tag": "section",
  "class": "hero-section",
  "limit": 1,
  "settings": [],
  "max_blocks": 16,
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:sections.hero.name" }],
  "enabled_on": { "templates": ["index"] },
  "disabled_on": { "templates": ["password"] }
}

ブロックの schema 構造

{
  "name": "t:blocks.slide.name",
  "tag": "div",
  "class": "slide",
  "settings": [],
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:blocks.slide.name" }]
}

設定タイプの選択表

必要な機能	設定タイプ	主なフィールド
オン／オフ切り替え	checkbox	default: true/false
短いテキスト	text	placeholder
長いテキスト	textarea	placeholder
リッチテキスト（<p> を含む）	richtext	—
インラインのリッチテキスト（<p> を含まない）	inline_richtext	—
数値入力	number	placeholder
スライダー	range	min、max、default（すべて必須）、step、unit
ドロップダウン／セグメント選択	select	options: [{value, label}]
ラジオボタン	radio	options: [{value, label}]
テキスト配置	text_alignment	default: "left"/"center"/"right"
カラーピッカー	color	default: "#000000"
画像のアップロード	image_picker	—
動画のアップロード	video	—
外部動画の URL	video_url	accept: ["youtube", "vimeo"]
商品ピッカー	product	—
コレクションピッカー	collection	—
ページピッカー	page	—
ブログピッカー	blog	—
記事ピッカー	article	—
URL の入力	url	—
メニューピッカー	link_list	—
フォントピッカー	font_picker	default（必須）
エディターの見出し	header	content（id は不要）
エディターの説明	paragraph	content（id は不要）

visible_if のパターン

{
  "visible_if": "{{ block.settings.layout == 'vertical' }}",
  "type": "select",
  "id": "alignment",
  "label": "t:labels.alignment",
  "options": [...]
}

他の設定値に応じて、エディター内の設定を条件付きで表示／非表示にします。

ブロックエントリーのタイプ

• { "type": "@theme" } — 任意のテーマブロックを受け付けます
• { "type": "@app" } — アプリブロックを受け付けます
• { "type": "slide" } — slide ブロックタイプのみを受け付けます

schema の詳細と全 33 種類の設定タイプ：references/schema-and-settings.md

CSS と JavaScript

コンポーネントごとのスタイルとスクリプト

セクション、ブロック、スニペット内で {% stylesheet %} と {% javascript %} を使用します。

{% stylesheet %}
  .my-component { display: flex; }
{% endstylesheet %}

{% javascript %}
  console.log('loaded');
{% endjavascript %}

• 各ファイルにつきタグはそれぞれ 1 つ — {% stylesheet %} タグを複数使うとエラーになります
• Liquid は使用できません — これらのタグでは Liquid は処理されません。代わりに CSS 変数またはクラスを使用してください
• sections/、blocks/、snippets/ 内でのみ使用できます

{% style %} タグ（Liquid 対応 CSS）

Liquid が必要な動的 CSS（エディターでリアルタイムに更新されるカラー設定など）に使用します。

{% style %}
  .section-{{ section.id }} {
    background: {{ section.settings.bg_color }};
  }
{% endstyle %}

設定用の CSS パターン

単一の CSS プロパティ — CSS 変数を使用します。

<div style="--gap: {{ block.settings.gap }}px">

複数の CSS プロパティ — 選択値として CSS クラスを使用します。

<div class="{{ block.settings.layout }}">

LiquidDoc（{% doc %}）

必須対象： スニペット（常に）、ブロック（{% content_for 'block' %} を使用して静的にレンダリングする場合）

{% doc %}
  Brief description of what this file renders.

  @param {type} name - Description of required parameter
  @param {type} [name] - Description of optional parameter (brackets = optional)

  @example
  {% render 'snippet-name', name: value %}
{% enddoc %}

パラメーターのタイプ： string、number、boolean、image、object、array

翻訳

ユーザーに表示されるすべての文字列で t フィルターを使用する必要があります

<h2>{{ 'sections.hero.heading' | t }}</h2>
<button>{{ 'products.add_to_cart' | t }}</button>


<h2>Welcome to our store</h2>

変数の補間

{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}

ロケールファイル：

{
  "products": {
    "price_range": "From {{ min }} to {{ max }}"
  }
}

ロケールファイルの構造

locales/
├── en.default.json          # English translations (required)
├── en.default.schema.json   # Editor setting translations (required)
├── fr.json                  # French translations
└── fr.schema.json           # French editor translations

キーの命名規則

• snake_case と階層化されたキー（最大3階層）を使用します
• すべてのテキストに文頭のみ大文字の形式を使用します
• スキーマのラベルには t: プレフィックスを使用します："label": "t:labels.heading"
• コンポーネントごとにグループ化します：sections.hero.heading、blocks.slide.title

リファレンス

• フィルター：言語（77）、HTML／メディア（45）、コマース（30）
• タグリファレンス（30個のタグ）
• オブジェクト：コマース（5）、コンテンツ（10）、ティア2（69）、ティア3（53）
• スキーマと設定のリファレンス（33種類）
• 完全な例（スニペット、ブロック、セクション）