GUIDE

2026.08.18

Clipkit テンプレート記述ガイド

Clipkit の Liquid テンプレートを、実務でそのまま使える形で説明するリファレンスです。フロントエンド実装者・テンプレート制作者を主な読者として想定しています。

第2章 Object リファレンス リファレンスの読み方 / 既定テンプレートとデフォルトオブジェクト / site / article / item / tag / category / user / request / paginate / comment / collection / collection_item / comment_asset / gallery / item_asset / form / form_reply / form_reply_value / controller / distributor / static_page / additional_field / article_attributes / article_favorites / user_attributes

第3章フィルタ・タグ・トップレベル変数 フィルタ（拡張） / タグ（制御・部品） / トップレベル変数

はじめに

本ドキュメントの位置づけ

本ドキュメントは、ClipkitにおけるLiquidテンプレートの記述方法を、実務で利用できる形で整理したものです。

記事一覧の表示、詳細ページの構築、タグやカテゴリの出力など、フロントエンド実装において必要となる処理を中心に扱います。

本ドキュメントで得られること

本ドキュメントを通じて、以下を習得できます。

記事一覧および詳細ページの基本的な構築方法
Liquidを用いたデータ出力の考え方
実装にそのまま適用できる記述パターン

対象読者

以下のような方を対象としています。

HTML / CSS / JavaScript を用いたページ制作を行う方
テンプレートの構築やカスタマイズを担当する方

本ドキュメントの進め方

最初に本書冒頭の「目次」を確認し、必要な節だけ参照してください。第1章から第3章まで通読する必要はありません。

基本と記述パターン: 「基本の使い方・記述パターン」節 — Liquid の書き方と実装パターン（初めて触る場合はここから）
第2章・第3章: オブジェクト・フィルタ・タグ等のリファレンス — 辞書として、必要なときだけ引く

取り扱わない内容

本ドキュメントでは、以下の内容は扱いません。

サーバサイドの実装詳細
Liquidの内部仕様
内部処理の仕組み

テンプレート実装に必要な範囲に限定しています。

コード例について

掲載しているコードは、テンプレートに直接適用できる形式で記載しています。

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

必要に応じてHTML構造やクラスを付与して利用してください。

Clipkit Liquid 基本の使い方

基本の使い方

概要

本ページでは、Liquidを用いてテンプレートを記述する際の基本的な考え方と記法を整理します。

ここで扱う内容を理解することで、後半の「基本的な記述パターン」をそのまま活用できるようになります。

基本構文

{{ site.title }}

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

{{ }}：データの出力
{% %}：処理の記述（繰り返し・条件分岐など）

データ処理の流れ

Liquidでは、データは以下の順序で処理されます。

object → filter → tag → 出力

object：データを取得する
filter：データを加工する
tag：表示や制御を行う

単数データと複数データ

単数データ

単一のデータは、そのまま出力できます。

{{ article.title }}

複数データ

複数のデータは、そのまま出力することはできません。
for / selectfor を用いて1件ずつ取り出します。

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

主なデータ

テンプレートでは、以下のデータを中心に扱います。

site：サイト全体の情報および記事一覧
article：個別の記事データ
user：記事の著者情報
category：記事のカテゴリ
tag：記事に紐づくタグ

記事一覧の表示

記事一覧を順に出力します。

{% selectfor (title) in site.articles %}
  {{ title }}
{% endselectfor %}

記事詳細の表示

現在の記事の基本情報を表示します。

{{ article.title }}
{{ article.description }}

本文の表示

記事本文は article.items を通じて出力します。

{% for item in article.items %}
  {{ item.render }}
{% endfor %}

まとめ

{{ }} は出力、{% %} は処理
複数データは for / selectfor で展開する
object → filter → tag の順で処理される

基本的な記述パターン

概要

本節では、実務で頻繁に利用する記述パターンを整理します。
ここで紹介するコードは、そのままテンプレートに適用できる形で記載しています。

記事一覧の表示

サイト内の記事を一覧として出力します。

{% selectfor (title) in site.articles %}
  {{ title }}
{% endselectfor %}

記事一覧（リンク付き）

記事タイトルにリンクを付与します。


{% selectfor (title, path) in site.articles %}
  
    
      {{ title }}
    
  
{% endselectfor %}

記事詳細の表示

現在の記事の基本情報を表示します。

{{ article.title }}
{{ article.description }}

本文の表示

記事本文を構成する要素を順に出力します。

{% for item in article.items %}
  {{ item.render }}
{% endfor %}

タグ一覧の表示

記事に紐づくタグを表示します。

{% for tag in article.tags %}
  {{ tag.name }}
{% endfor %}

カテゴリの表示

記事のカテゴリを表示します。

{{ article.category.name }}

著者の表示

記事の著者情報を表示します。

{{ article.user.name }}

コメント一覧の表示

記事に紐づくコメントを表示します。

{% for comment in article.comments %}
  {{ comment.body }}
{% endfor %}

ページネーション

記事一覧をページ単位で分割して表示します。

{% assign articles = site.articles %}
{% paginate articles per 10 %}
  {% selectfor (title) in paginate.collection %}
    {{ title }}
  {% endselectfor %}
{% endpaginate %}

件数制限

表示件数を制限します。

{% assign articles = site.articles | limit: 5 %}

{% selectfor (title) in articles %}
  {{ title }}
{% endselectfor %}

並び替え

記事の表示順を制御します。

{% assign articles = site.articles | order: 'published_at DESC' %}

{% selectfor (title) in articles %}
  {{ title }}
{% endselectfor %}

検索結果の表示

検索結果に応じて記事を表示します。

{% assign q = request.params["q"] %}
{% if q == blank %}
  {% assign q = "" %}
{% endif %}
{% assign articles = site.articles | search: q %}

{% selectfor (title) in articles %}
  {{ title }}
{% endselectfor %}

条件による絞り込み

条件に一致する記事のみを表示します。

{% assign articles = site.articles | where: "category_id = ?", category.id %}

{% selectfor (title) in articles %}
  {{ title }}
{% endselectfor %}

まとめ

実装は「パターン」を基に組み立てる
必要に応じて filter を組み合わせる
詳細仕様はリファレンスで確認する

リファレンスの読み方

この章は、ClipkitのLiquidで使うデータの一覧＝リファレンスです。
目的は「仕組みを理解すること」より実装できることです。

このリファレンスでの用語

オブジェクト：site / article / item / tag のような “データのかたまり”
プロパティ：article.title の .title のように、オブジェクトから取り出せる値
list（繰り返し可能）：site.articles のように、for / selectfor で回して1件ずつ扱うもの

このガイドでは、厳密な言語仕様（「メソッドとは」など）の説明はしません。
代わりに「何が取れるか」と最小の書き方を揃えます。

既定テンプレートと、デフォルトで渡される変数

Clipkit には、デフォルトテーマの既定テンプレートがあります。テンプレートの種類（一覧・詳細など）により、文脈として渡されるオブジェクトが変わります。

既定テンプレート（代表）

layout（共通レイアウト）
index（トップ・一覧）
show（記事の詳細）
category_show（カテゴリの一覧）
tag_show（タグの一覧）
user_show（ユーザーの一覧・詳細）
mail_article（メール用）
error_404（404）

※ 端末向けの派生として _mobile や show_amp が用意される場合があります。

既定テンプレートと、文脈で渡されるデフォルトオブジェクト（変数名の方針）は、本書内の「既定テンプレートとデフォルトオブジェクト」の節で扱います。

どのテンプレートでも参照しやすい変数

テンプレートの多くで参照しやすい「トップレベル変数」は、第3章で扱います。

まず覚える読み方（最小）

1) 値の出力（`{{ }}`）

{{ site.title }}
{{ article.title }}

2) 一覧の展開（`for` / `selectfor`）

listはそのまま {{ site.articles }} のように表示できません。
基本は for / selectfor で1件ずつ取り出します。

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

「型」表記について（重要）

リファレンス内の「型」表記は、読み手が迷わないように固定ルールで揃えます。
型の表記は、本書内で一貫して揃えます（例: list / object）。

オブジェクト（`03-`）を読む順番（最小）

迷ったときは、各オブジェクトのページを次の順で読みます。

関連リレーション（どこから辿れるか、どれとつながるか）
アクセス（{{ object.xxx }} の最小形）
サンプルコード（よくある表示）
プロパティ（取り出せる値）

迷ったときの見方

オブジェクト同士の関係（どれがどれにぶら下がるか）は、各オブジェクトの「関連リレーション」「構造」を入口にして辿ります。
実装の組み立ては、第1章で扱います。
値の加工（絞り込み、並び替え、件数制限、文字列の整形など）は、第3章「フィルタ」で扱います。
制御・部品（if / for / paginate など）は、第3章「タグ」で扱います。

リファレンス（03-）は「各オブジェクトで何が取れるか」の確認に使います。
実装の完成形はパターン側で作る、という役割分担です。

既定テンプレートとデフォルトオブジェクト

導入

Clipkit のテーマには既定テンプレートがあります。
既定テンプレートには、既定名で参照できるオブジェクト（デフォルトオブジェクト）があり、画面（テンプレート）の文脈に応じて渡されます。

本ページは、既定テンプレートとデフォルトオブジェクトの考え方を整理し、制作者が定義する変数と混同しないための方針（命名・退避）を示します。

誰向けか

Clipkit のテンプレートを編集し、既存のテーマを保守・改稿する担当者向けです。

扱う範囲

デフォルトテーマの既定テンプレート名と、そこで登場しやすいデフォルトオブジェクト（代表例）を扱います。
デフォルトオブジェクトのプロパティ一覧は、本ページでは列挙しません。必要に応じて第2章の各リファレンスを参照してください。
トップレベル変数（request / system など）の入口は、第3章で扱います。

既定テンプレート

次は、デフォルトテーマの既定テンプレート名です。

layout（共通レイアウト）
index（トップ・一覧）
show（記事の詳細）
category_show（カテゴリの一覧）
tag_show（タグの一覧）
user_show（ユーザーの一覧・詳細）
mail_article（メール用）
error_404（404）

※ 端末向けの派生として _mobile や show_amp が用意される場合があります。

デフォルトオブジェクト（文脈で渡される代表例）

デフォルトオブジェクトは、テンプレート（画面）の文脈に応じて渡されるオブジェクトです。代表例は次のとおりです。

index: site（サイト全体の入口）、必要に応じて category
show: article（記事の詳細）
category_show: category（カテゴリ）
tag_show: tag（タグ）
user_show: user（ユーザー）

上記は代表例です。実際に渡されるオブジェクトは、テーマや画面の構成によって異なる場合があります。

参照先（リファレンス）

site（サイト）
article（記事）
category（カテゴリ）
tag（タグ）
user（ユーザー）

オブジェクト同士の関係（全体像）は、各オブジェクトの「関連リレーション」「構造」から辿ります。

制作者が定義する変数と混同しない（命名と退避）

テンプレートでは、デフォルトオブジェクト（例: site / article）と、制作者が assign 等で定義する変数が同じ名前になると、読み手が文脈を誤解しやすくなります。次の方針を推奨します。

1) 既定名（デフォルトオブジェクト名）を再利用しない

site / article / tag / category / user のような既定名は、制作者の変数名として再利用しないことを推奨します。

2) 制作者の変数には接頭辞を付ける

制作者が定義する変数は、既定名と区別できる接頭辞を付けます（例: custom_ / tmp_ / v_ など）。

{% assign custom_articles = site.articles | limit: 5 %}
{% selectfor (title) in custom_articles %}
  {{ title }}
{% endselectfor %}

3) やむを得ず既定名を上書きする場合は、先に退避する

既定名を上書きしない運用が基本です。
ただし、既存テーマの互換などで、やむを得ず既定名を上書きする場合は、先に別名へ退避してから行います。

{% assign default_site = site %}
{% assign site = default_site %}

退避名は、既定名と混同しにくいもの（例: default_site / default_article）を用います。

参照ガイド

制御・部品（タグ）は、第3章で扱います。
加工（フィルタ）は、第3章で扱います。
トップレベル変数の入口は、第3章で扱います。

site

サイト全体の入口データです。

リファレンスの読み方（{{ }} / for / 型表記ルール）は、先に次を参照してください。

03 リファレンスの読み方（まずここ）
03 リファレンスの「型」表記ルール（重要）

構造

site
├─ articles（list: article）
├─ tags（list: tag）
├─ categories（list: category）
├─ pages（list）
├─ contents（list）
├─ collections（list: collection）
├─ users（list: user）
└─ comments（list: comment）

型

単数

アクセス

{{ site.xxx }}

サンプルコード

このリファレンスは「siteの入口（何が取れるか）」が主目的です。
一覧の組み立てやレイアウトは『パターン（patterns）』の項目を確認してください。加工は『フィルタ（拡張）』、制御は『タグ（制御・部品）』の項目を確認してください。

サイトタイトル

{{ site.title }}

記事一覧（最小）

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

タグ一覧（最小）

{% for tag in site.tags %}
  {{ tag.name }}
{% endfor %}

プロパティ一覧

並び順は掲載されている順番を維持します（並べ替え禁止）。

current

役割: 現在表示しているページの文脈情報を参照します（詳細は利用中テーマの挙動に従います）。

{{ site.current }}

cache_key

型：string

役割: キャッシュ用のキーです。

{{ site.cache_key }}

title

型：string

役割: サイト名（表示用）です。

{{ site.title }}

top_title

型：string

役割: トップページ向けのタイトル文字列です。

{{ site.top_title }}

name

型：string

役割: サイト識別名（URL 等に使われる名称）です。

{{ site.name }}

description

型：string

役割: サイトの説明文です。

{{ site.description }}

url

型：string

役割: サイトのURLです。

{{ site.url }}

path

型：string

役割: サイトのパスです。

{{ site.path }}

all_articles

型：list（article）

役割: サイト内のすべての記事一覧です。

{% selectfor (title) in site.all_articles %}
  {{ title }}
{% endselectfor %}

published_articles（=articles/recent_articles）

型：list（article）

役割: 公開状態の記事一覧です。

テンプレートでは site.articles と書くことが多く、同じlistです。

{% selectfor (title) in site.articles %}
  {{ title }}
{% endselectfor %}

updated_articles

型：list（article）

役割: 更新日時の新しい順などで参照する記事一覧です（挙動は環境により異なる場合があります）。

{% selectfor (title) in site.updated_articles %}
  {{ title }}
{% endselectfor %}

private_articles

型：list（article）

役割: 非公開の記事一覧です。

{% selectfor (title) in site.private_articles %}
  {{ title }}
{% endselectfor %}

reserved_articles

型：list（article）

役割: 公開予約中の記事一覧です。

{% selectfor (title) in site.reserved_articles %}
  {{ title }}
{% endselectfor %}

all_pages

型：list

役割: ページ相当のデータ一覧です（内容は環境により異なる場合があります）。

{% for page in site.all_pages %}
  {{ page }}
{% endfor %}

pages

型：list

役割: 公開状態のページ相当データ一覧です（内容は環境により異なる場合があります）。

{% for page in site.pages %}
  {{ page }}
{% endfor %}

all_contents

型：list

役割: コンテンツ相当のデータ一覧です（内容は環境により異なる場合があります）。

{% for content in site.all_contents %}
  {{ content }}
{% endfor %}

private_contents

型：list

役割: 非公開のコンテンツ相当データ一覧です（内容は環境により異なる場合があります）。

{% for content in site.private_contents %}
  {{ content }}
{% endfor %}

private_pages

型：list

役割: 非公開のページ相当データ一覧です（内容は環境により異なる場合があります）。

{% for page in site.private_pages %}
  {{ page }}
{% endfor %}

型：list

役割: 公開状態のコンテンツ相当データ一覧です（内容は環境により異なる場合があります）。

{% for content in site.contents %}
  {{ content }}
{% endfor %}

popular_articles（deprecated）

型：list（article）（deprecated）

役割: 人気記事の一覧です（非推奨）。

{% selectfor (title) in site.popular_articles %}
  {{ title }}
{% endselectfor %}

custom_period_popular_articles

型：list（article）

役割: 任意期間の人気記事一覧です。

{% selectfor (title) in site.custom_period_popular_articles %}
  {{ title }}
{% endselectfor %}

daily_popular_articles

型：list（article）

役割: 日別の人気記事一覧です。

{% selectfor (title) in site.daily_popular_articles %}
  {{ title }}
{% endselectfor %}

weekly_popular_articles

型：list（article）

役割: 週別の人気記事一覧です。

{% selectfor (title) in site.weekly_popular_articles %}
  {{ title }}
{% endselectfor %}

monthly_popular_articles

型：list（article）

役割: 月別の人気記事一覧です。

{% selectfor (title) in site.monthly_popular_articles %}
  {{ title }}
{% endselectfor %}

total_popular_articles

型：list（article）

役割: 累計の人気記事一覧です。

{% selectfor (title) in site.total_popular_articles %}
  {{ title }}
{% endselectfor %}

custom_period_popular_users

型：list（user）

役割: 任意期間の人気ユーザー一覧です。

{% for user in site.custom_period_popular_users %}
  {{ user.name }}
{% endfor %}

daily_popular_users

型：list（user）

役割: 日別の人気ユーザー一覧です。

{% for user in site.daily_popular_users %}
  {{ user.name }}
{% endfor %}

weekly_popular_users

型：list（user）

役割: 週別の人気ユーザー一覧です。

{% for user in site.weekly_popular_users %}
  {{ user.name }}
{% endfor %}

monthly_popular_users

型：list（user）

役割: 月別の人気ユーザー一覧です。

{% for user in site.monthly_popular_users %}
  {{ user.name }}
{% endfor %}

total_popular_users

型：list（user）

役割: 累計の人気ユーザー一覧です。

{% for user in site.total_popular_users %}
  {{ user.name }}
{% endfor %}

custom_period_popular_tags

型：list（tag）

役割: 任意期間の人気タグ一覧です。

{% for tag in site.custom_period_popular_tags %}
  {{ tag.name }}
{% endfor %}

daily_popular_tag_pages

型：list

役割: 日別の人気タグページ相当データ一覧です（内容は環境により異なる場合があります）。

{% for page in site.daily_popular_tag_pages %}
  {{ page }}
{% endfor %}

weekly_popular_tag_pages

型：list

役割: 週別の人気タグページ相当データ一覧です（内容は環境により異なる場合があります）。

{% for page in site.weekly_popular_tag_pages %}
  {{ page }}
{% endfor %}

monthly_popular_tag_pages

型：list

役割: 月別の人気タグページ相当データ一覧です（内容は環境により異なる場合があります）。

{% for page in site.monthly_popular_tag_pages %}
  {{ page }}
{% endfor %}

popular_tags

型：list（tag）

役割: 人気タグの一覧です。

{% for tag in site.popular_tags %}
  {{ tag.name }}
{% endfor %}

all_tags

型：list（tag）

役割: サイト内のすべてのタグ一覧です。

{% for tag in site.all_tags %}
  {{ tag.name }}
{% endfor %}

all_categories

型：list（category）

役割: サイト内のすべてのカテゴリ一覧です。

{% for category in site.all_categories %}
  {{ category.name }}
{% endfor %}

files

型：list

役割: サイト内のファイル相当データ一覧です（内容は環境により異なる場合があります）。

{% for file in site.files %}
  {{ file }}
{% endfor %}

manageable

型：boolean

役割: サイトが管理可能な状態かどうかを表します。

{{ site.manageable }}

curators

型：list（user）

役割: ライター（運用担当）ユーザーの一覧です。

{% for user in site.curators %}
  {{ user.name }}
{% endfor %}

accept_comment

型：boolean

役割: コメントを受け付けるかどうかを表します。

{{ site.accept_comment }}

comments

型：list（comment）

役割: コメントの一覧です。

{% for comment in site.comments %}
  {{ comment.body }}
{% endfor %}

num_comments

型：integer

役割: コメント件数です。

{{ site.num_comments }}

attribute_fields

型：list

役割: 拡張項目の定義一覧です（内容は環境により異なる場合があります）。

{% for field in site.attribute_fields %}
  {{ field }}
{% endfor %}

collections

型：list（collection）

役割: コレクションの一覧です。

{% for collection in site.collections %}
  {{ collection.name }}
{% endfor %}

recaptcha_site_key

型：string

役割: reCAPTCHA のサイトキーです。

{{ site.recaptcha_site_key }}

link_option

役割: リンクの表示・挙動に関する設定値です（内容は環境により異なる場合があります）。

{{ site.link_option }}

is_private_mode

型：boolean

役割: 非公開モードかどうかを表します。

{{ site.is_private_mode }}

users

型：list（user）

役割: サイト内ユーザーの一覧です。

{% for user in site.users %}
  {{ user.name }}
{% endfor %}

メモ

記事一覧は site.articles の利用を基本とします。
popular_articles は deprecated です（新規利用は推奨しません）。
list系は基本 for で1件ずつ扱います。

注意

複数データはそのまま表示できません。
一覧表示には for を使います。

article

現在の記事データです。

リファレンスの読み方（{{ }} / for / 型表記ルール）は、先に次を参照してください。

03 リファレンスの読み方（まずここ）
03 リファレンスの「型」表記ルール（重要）

構造

article
├─ category（object: category）
├─ user（object: user）
├─ distributor（object: distributor）
├─ site（object: site）
├─ attributes（object: article.attributes）
├─ favorites（object: article.favorites）
├─ tags（list: tag）
├─ ordered_tags（list: tag）
├─ items（list: item）
├─ subscribed_items（list: item）
├─ comments（list: comment）
├─ paginates（list: paginate）
├─ relevance_articles（list: article）
└─ locales（list: article）

型

単数

アクセス

{{ article.xxx }}

サンプルコード

このリファレンスは「プロパティ参照」が主目的です。
一覧の組み立てやレイアウトは『パターン（patterns）』の項目を確認してください。加工は『フィルタ（拡張）』、制御は『タグ（制御・部品）』の項目を確認してください。

基本（表示）

タイトル

{{ article.title }}

タイトルを見出しとして表示する

{{ article.title }}

説明文

{{ article.description }}

説明文を段落として表示する

{{ article.description }}

リンク（記事）

記事リンク（path）

{{ article.title }}

記事URL

{{ article.url }}

日付

公開日

{{ article.published_at }}

更新日

{{ article.updated_at }}

本文

本文（itemsをrenderで出す）

{% for item in article.items %}
  {{ item.render }}
{% endfor %}

本文（要素ごとに扱う）

{% for item in article.items %}
  {{ item.title }}
  {{ item.body }}
{% endfor %}

subscribed_items の表示

{% for item in article.subscribed_items %}
  {{ item.render }}
{% endfor %}

コメント一覧

{% for comment in article.comments %}
  {{ comment.body }}
{% endfor %}

コメント一覧（投稿者付き）

{% for comment in article.comments %}
  
    {{ comment.user.name }}
    {{ comment.body }}
  
{% endfor %}

{% for related in article.relevance_articles %}
  {{ related.title }}
{% endfor %}

言語別

言語別記事

{% for locale_article in article.locales %}
  {{ locale_article.title }}
{% endfor %}

数値

閲覧数

{{ article.num_views }}

コメント数

{{ article.num_comments }}

お気に入り数

{{ article.num_favorites }}

導線（お気に入り・コメント）

お気に入り追加リンク

お気に入り追加

お気に入り解除リンク

お気に入り解除

コメント一覧ページへのリンク

コメントを見る

コメント投稿ページへのリンク

コメントする

画像

アイキャッチ画像

アイキャッチ画像（ある場合だけ表示）

{% unless article.image_is_empty %}
  
{% endunless %}

その他

拡張項目

{{ article.attributes.xxx }}

サイト

{{ article.site.title }}

プロパティ

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ article.cache_key }}

description

型：string

役割: 記事の説明文です。

{{ article.description }}

id

型：integer

役割: 記事IDです。

{{ article.id }}

kind

役割: 記事種別を参照します（古いバージョン由来の項目のため、新規利用は kinds を推奨します）。

{{ article.kind }}

kinds

役割: 記事種別を参照します。

{{ article.kinds }}

lang

型：string

役割: 記事の言語コードです。

{{ article.lang }}

original_id

型：integer

役割: 元記事のIDです（言語別記事等で参照します）。

{{ article.original_id }}

permalink

型：string

役割: 記事のパーマリンクです。

{{ article.permalink }}

title

型：string

役割: 記事タイトルです。

{{ article.title }}

type

役割: 記事タイプを表す値です（内容は環境により異なる場合があります）。

{{ article.type }}

パス/URL

add_favorite_path

型：string

役割: お気に入り追加のパスです。

{{ article.add_favorite_path }}

comments_path

型：string

役割: コメント一覧ページへのパスです。

{{ article.comments_path }}

favorites_json_url

型：string

役割: お気に入り情報（JSON）へのURLです。

{{ article.favorites_json_url }}

new_comment_path

型：string

役割: コメント投稿ページへのパスです。

{{ article.new_comment_path }}

path

型：string

役割: 記事詳細ページへのパスです。

{{ article.path }}

remove_favorite_path

型：string

役割: お気に入り解除のパスです。

{{ article.remove_favorite_path }}

source_url

型：string

役割: 配信元（元URL）を表すURLです。

{{ article.source_url }}

url

型：string

役割: 記事詳細ページへのURLです。

{{ article.url }}

画像

image_is_empty

型：boolean

役割: 関連画像が未設定かどうかを表します。

{{ article.image_is_empty }}

日時

published_at

型：datetime

役割: 公開日時です。

{{ article.published_at }}

updated_at

型：datetime

役割: 更新日時です。

{{ article.updated_at }}

状態・件数

is_favorite

型：boolean

役割: 現在のユーザーがお気に入り登録しているかどうかを表します。

{{ article.is_favorite }}

is_published

型：boolean

役割: 公開状態かどうかを表します。

{{ article.is_published }}

nordot?

型：boolean

役割: 記事の表示条件に関する判定値です（内容は環境により異なる場合があります）。

{{ article.nordot? }}

num_comments

型：integer

役割: コメント件数です。

{{ article.num_comments }}

num_favorites

型：integer

役割: お気に入り数です。

{{ article.num_favorites }}

num_views

型：integer

役割: 閲覧数です。

{{ article.num_views }}

num_visits

型：integer

役割: 訪問数です。

{{ article.num_visits }}

has_subscription

型：boolean

役割: 購読（subscription）情報を持つかどうかを表します。

{{ article.has_subscription }}

リレーション

comments

型：list（comment） → comment に関連

役割: 記事に紐づくコメント一覧です。

{% for comment in article.comments %}
  {{ comment.body }}
{% endfor %}

distributor

型：object（distributor） → distributor に関連

役割: 記事の配信元（ディストリビュータ）です。

{{ article.distributor.name }}

favorites

型：object → article.favorites に関連

役割: お気に入り集計オブジェクトです。

{{ article.favorites }}

items

型：list（item） → item に関連

役割: 記事本文を構成する要素（item）の一覧です。

{% for item in article.items %}
  {{ item.render }}
{% endfor %}

locales

型：list（article） → article に関連

役割: 言語別の記事一覧です。

{% for locale_article in article.locales %}
  {{ locale_article.title }}
{% endfor %}

ordered_tags

型：list（tag） → tag に関連

役割: 記事に紐づくタグ一覧（順序付き）です。

{% for tag in article.ordered_tags %}
  {{ tag.name }}
{% endfor %}

paginates

型：list（paginate） → paginate に関連

役割: ページネーション情報の一覧です。

{% for paginate in article.paginates %}
  {{ paginate }}
{% endfor %}

relevance_articles

型：list（article） → article に関連

役割: 関連記事の一覧です。

{% for related in article.relevance_articles %}
  {{ related.title }}
{% endfor %}

site

型：object（site） → site に関連

役割: 記事が属するサイトです。

{{ article.site.title }}

subscribed_items

型：list（item） → item に関連

役割: 購読（subscription）に関連する要素（item）の一覧です。

{% for item in article.subscribed_items %}
  {{ item.render }}
{% endfor %}

user

型：object（user） → user に関連

役割: 記事の著者（ユーザー）です。

{{ article.user.name }}

attributes

型：object → article.attributes に関連

役割: 記事の拡張項目です（動的な項目）。

{{ article.attributes.xxx }}

メモ

category / distributor / favorites / site / user / attributes は単数データです。
comments / items / locales / ordered_tags / paginates / relevance_articles / subscribed_items / tags は複数データです。
複数データは for を使って展開します。
記事本文は通常 article.items を使って出力します。

注意

複数データはそのまま表示できません。
一覧表示には for を使います。

item

記事本文などを構成する要素（アイテム）データです。 article.items の for ループ内で使います。

構造

item
├─ title / body / url ...（基本フィールド）
└─ galleries（list: gallery）

型

単数

アクセス

{{ item.xxx }}

サンプルコード

要素をそのまま描画（基本）

{{ item.render }}

タイトルと本文を自分で組み立てる

{{ item.title }}
{{ item.body }}

ギャラリー一覧

{% for gallery in item.galleries %}
  {{ gallery.title }}
{% endfor %}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ item.cache_key }}

render

型：string

役割: item を既定の表示で描画した結果（HTML）です。

{{ item.render }}

permalink

型：string

役割: item の識別子です。

{{ item.permalink }}

sortkey

型：string

役割: 表示順に関するキーです。

{{ item.sortkey }}

type

役割: item の種類（タイプ）を表す値です。

{{ item.type }}

title

型：string

役割: タイトルです。

{{ item.title }}

caption

型：string

役割: キャプション（説明）です。

{{ item.caption }}

alt

型：string

役割: 画像等の代替テキスト（alt）です。

{{ item.alt }}

url

型：string

役割: URL文字列です（リンク先等）。

{{ item.url }}

is_local_url

型：boolean

役割: url がサイト内のURLかどうかを表します。

{{ item.is_local_url }}

source

型：string

役割: 配信元などの出典文字列です。

{{ item.source }}

body

型：string

役割: 本文（内容）です。

{{ item.body }}

comment

型：string

役割: コメント（補足）です。

{{ item.comment }}

player_url

型：string

役割: プレイヤーURLです（メディア種別により使います）。

{{ item.player_url }}

ext1

型：string

役割: 拡張情報（1）です（内容は環境により異なる場合があります）。

{{ item.ext1 }}

ext2

型：string

役割: 拡張情報（2）です（内容は環境により異なる場合があります）。

{{ item.ext2 }}

ext3

型：string

役割: 拡張情報（3）です（内容は環境により異なる場合があります）。

{{ item.ext3 }}

画像

image_is_empty

型：boolean

役割: 関連画像が未設定かどうかを表します。

{{ item.image_is_empty }}

画像サイズ

image_original_width

型：integer

役割: オリジナル画像の横幅（px）です。

{{ item.image_original_width }}

image_original_height

型：integer

役割: オリジナル画像の高さ（px）です。

{{ item.image_original_height }}

image_large_width

型：integer

役割: large（例: 1280px）サイズ画像の横幅（px）です。

{{ item.image_large_width }}

image_large_height

型：integer

役割: large（例: 1280px）サイズ画像の高さ（px）です。

{{ item.image_large_height }}

image_medium_width

型：integer

役割: medium（例: 640px）サイズ画像の横幅（px）です。

{{ item.image_medium_width }}

image_medium_height

型：integer

役割: medium（例: 640px）サイズ画像の高さ（px）です。

{{ item.image_medium_height }}

image_small_width

型：integer

役割: small（例: 320px）サイズ画像の横幅（px）です。

{{ item.image_small_width }}

image_small_height

型：integer

役割: small（例: 320px）サイズ画像の高さ（px）です。

{{ item.image_small_height }}

image_square_width

型：integer

役割: square（例: 150px 正方形）サイズ画像の横幅（px）です。

{{ item.image_square_width }}

image_square_height

型：integer

役割: square（例: 150px 正方形）サイズ画像の高さ（px）です。

{{ item.image_square_height }}

image_thumbnail_width

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の横幅（px）です。

{{ item.image_thumbnail_width }}

image_thumbnail_height

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の高さ（px）です。

{{ item.image_thumbnail_height }}

その他

domain

型：string

{{ item.domain }}

getty_id

型：string

{{ item.getty_id }}

ファイル

file_name

型：string

{{ item.file_name }}

file_content_type

型：string

{{ item.file_content_type }}

file_size

型：integer

{{ item.file_size }}

file_url

型：string

役割: 添付ファイルのURLです。

{{ item.file_url }}

file_download

型：string

役割: 添付ファイルのダウンロード用パスです。

{{ item.file_download }}

リレーション

galleries

型：list（gallery）

役割: ギャラリー（画像一覧）です（item の種類により存在しない場合があります）。

{% for gallery in item.galleries %}
  {{ gallery.title }}
{% endfor %}

メモ

本文出力の定番は {{ item.render }} です（要素タイプにより中身が変わります）。
galleries はlistなので for で展開します。

tag

タグ（分類ラベル）データです。

構造

tag
├─ name / description / path / url ...（基本フィールド）
├─ recent_articles（list: article）
├─ all_articles（list: article）
├─ private_articles（list: article）
├─ reserved_articles（list: article）
├─ all_pages（list）
├─ all_contents（list）
├─ related_tags（list: tag）
├─ children（list: tag）
├─ descendants（list: tag）
├─ ancestors（list: tag）
├─ parent（object: tag）
├─ tag_contents（list）
├─ tag_articles（list）
└─ tag_pages（list）

型

単数

アクセス

{{ tag.xxx }}

サンプルコード

タグ名

{{ tag.name }}

タグリンク

{{ tag.name }}

タグ配下の記事一覧（例）

{% selectfor (title, path) in tag.recent_articles %}
  {{ title }}
{% endselectfor %}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ tag.cache_key }}

name

型：string

役割: タグ名です。

{{ tag.name }}

description

型：string

役割: タグの説明文です。

{{ tag.description }}

num_articles

型：integer

役割: タグに紐づく記事数です。

{{ tag.num_articles }}

recent_articles

型：list（article）

役割: タグ配下の公開記事一覧です。

{% selectfor (title) in tag.recent_articles %}
  {{ title }}
{% endselectfor %}

path

型：string

役割: タグページへのパスです。

{{ tag.path }}

permalink

型：string

役割: タグのパーマリンクです。

{{ tag.permalink }}

url

型：string

役割: タグページへのURLです。

{{ tag.url }}

画像

has_image

型：boolean

役割: タグ画像が設定されているかどうかを表します。

{{ tag.has_image }}

記事/ページ/コンテンツ

all_articles

型：list（article）

役割: タグ配下の全記事一覧です（ごみ箱内の記事は含みません）。

{% selectfor (title) in tag.all_articles %}
  {{ title }}
{% endselectfor %}

private_articles

型：list（article）

役割: タグ配下の非公開記事一覧です。

{% selectfor (title) in tag.private_articles %}
  {{ title }}
{% endselectfor %}

reserved_articles

型：list（article）

役割: タグ配下の公開予約中の記事一覧です。

{% selectfor (title) in tag.reserved_articles %}
  {{ title }}
{% endselectfor %}

all_pages

型：list

役割: タグ配下のページ相当データ一覧です（ごみ箱内のページは含みません）。

{% for page in tag.all_pages %}
  {{ page }}
{% endfor %}

all_contents

型：list

役割: タグ配下のコンテンツ相当データ一覧です（ごみ箱内のコンテンツは含みません）。

{% for content in tag.all_contents %}
  {{ content }}
{% endfor %}

タグの階層

related_tags

型：list（tag）

役割: 関連タグの一覧です（子孫タグを含む場合があります）。

{% for related in tag.related_tags %}
  {{ related.name }}
{% endfor %}

children

型：list（tag）

役割: 子タグ（1階層下）の一覧です。

{% for child in tag.children %}
  {{ child.name }}
{% endfor %}

descendants

型：list（tag）

役割: 子孫タグ（下位の全階層）の一覧です。

{% for descendant in tag.descendants %}
  {{ descendant.name }}
{% endfor %}

ancestors

型：list（tag）

役割: 祖先タグ（上位の全階層）の一覧です。

{% for ancestor in tag.ancestors %}
  {{ ancestor.name }}
{% endfor %}

parent

型：object（tag）

役割: 親タグ（1階層上）です。

{{ tag.parent.name }}

タグページ

tag_contents

型：list

{% for x in tag.tag_contents %}
  {{ x }}
{% endfor %}

tag_articles

型：list

{% for x in tag.tag_articles %}
  {{ x }}
{% endfor %}

tag_pages

型：list

{% for x in tag.tag_pages %}
  {{ x }}
{% endfor %}

メモ

recent_articles / all_articles など list系は for が基本です。
parent は単数（object）なので、{{ tag.parent.name }} のように下位プロパティへ繋げます。

user

ユーザー（著者/会員など）データです。

構造

user
├─ name / email / nickname ...（基本フィールド）
├─ articles（list: article）
├─ private_articles（list: article）
├─ all_articles（list: article）
├─ reserved_articles（list: article）
├─ favorite_articles（list: article）
├─ all_pages（list）
├─ all_contents（list）
├─ followers（list: user）
├─ followees（list: user）
├─ attributes（object: user.attributes）
├─ user_contents（list）
├─ user_articles（list）
└─ user_pages（list）

型

単数

アクセス

{{ user.xxx }}

サンプルコード

表示名

{{ user.name }}

プロフィールページへのリンク

{{ user.name }}

ユーザーの記事一覧（例）

{% selectfor (title, path) in user.articles %}
  {{ title }}
{% endselectfor %}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ user.cache_key }}

name

型：string

役割: 表示名です。

{{ user.name }}

email

型：string

役割: メールアドレスです。

{{ user.email }}

nickname

型：string

役割: ニックネームです。

{{ user.nickname }}

bio

型：string

役割: 自己紹介文です。

{{ user.bio }}

first_name

型：string

役割: 名（first name）です。

{{ user.first_name }}

last_name

型：string

役割: 姓（last name）です。

{{ user.last_name }}

first_name_kana

型：string

役割: 名（かな）です。

{{ user.first_name_kana }}

last_name_kana

型：string

役割: 姓（かな）です。

{{ user.last_name_kana }}

full_name

型：string

役割: 氏名（フルネーム）です。

{{ user.full_name }}

full_name_kana

型：string

役割: 氏名（かな）です。

{{ user.full_name_kana }}

birthday

型：string

役割: 生年月日です。

{{ user.birthday }}

age

型：integer

役割: 年齢です。

{{ user.age }}

zip

型：string

役割: 郵便番号です。

{{ user.zip }}

pref

型：string

役割: 都道府県です。

{{ user.pref }}

address1

型：string

役割: 住所（1行目）です。

{{ user.address1 }}

address2

型：string

{{ user.address2 }}

email2

型：string

役割: メールアドレス（予備）です。

{{ user.email2 }}

phone1

型：string

役割: 電話番号（1）です。

{{ user.phone1 }}

phone2

型：string

役割: 電話番号（2）です。

{{ user.phone2 }}

id

型：integer

役割: ユーザーIDです。

{{ user.id }}

permalink

型：string

役割: ユーザーのパーマリンクです。

{{ user.permalink }}

url1

型：string

役割: 外部URL（1）です。

{{ user.url1 }}

url2

型：string

役割: 外部URL（2）です。

{{ user.url2 }}

url3

型：string

役割: 外部URL（3）です。

{{ user.url3 }}

状態・権限

is_official

型：boolean

役割: 公式（official）ユーザーかどうかを表します。

{{ user.is_official }}

kinds

役割: ユーザー種別を参照します（内容は環境により異なる場合があります）。

{{ user.kinds }}

roles

役割: 権限（ロール）の一覧です。

{{ user.roles }}

パス/URL

path

型：string

役割: プロフィールページへのパスです。

{{ user.path }}

url

型：string

役割: プロフィールページへのURLです。

{{ user.url }}

画像

状態・件数

num_views

型：integer

役割: 閲覧数です。

{{ user.num_views }}

is_admin

型：boolean

役割: 管理者かどうかを表します。

{{ user.is_admin }}

is_curator

型：boolean

役割: ライター（運用担当）かどうかを表します。

{{ user.is_curator }}

記事/ページ/コンテンツ

articles

型：list（article）

役割: ユーザーが作成した公開記事一覧です。

{% selectfor (title) in user.articles %}
  {{ title }}
{% endselectfor %}

private_articles

型：list（article）

役割: ユーザーが作成した非公開記事一覧です。

{% selectfor (title) in user.private_articles %}
  {{ title }}
{% endselectfor %}

all_articles

型：list（article）

役割: ユーザーが作成した全記事一覧です（ごみ箱内の記事は含みません）。

{% selectfor (title) in user.all_articles %}
  {{ title }}
{% endselectfor %}

reserved_articles

型：list（article）

役割: ユーザーが作成した公開予約中の記事一覧です。

{% selectfor (title) in user.reserved_articles %}
  {{ title }}
{% endselectfor %}

favorite_articles

型：list（article）

役割: ユーザーがお気に入り登録した記事一覧です。

{% selectfor (title) in user.favorite_articles %}
  {{ title }}
{% endselectfor %}

all_pages

型：list

役割: ユーザー配下のページ相当データ一覧です（ごみ箱内のページは含みません）。

{% for page in user.all_pages %}
  {{ page }}
{% endfor %}

all_contents

型：list

役割: ユーザー配下のコンテンツ相当データ一覧です（ごみ箱内のコンテンツは含みません）。

{% for content in user.all_contents %}
  {{ content }}
{% endfor %}

フォロー

followers

型：list（user）

役割: ユーザーをフォローしているユーザー一覧です。

{% for follower in user.followers %}
  {{ follower.name }}
{% endfor %}

followees

型：list（user）

役割: ユーザーがフォローしているユーザー一覧です。

{% for followee in user.followees %}
  {{ followee.name }}
{% endfor %}

is_follower

型：boolean

役割: 現在のユーザーが、このユーザーをフォローしているかどうかを表します。

{{ user.is_follower }}

add_follower_path

型：string

役割: フォローするためのパスです。

{{ user.add_follower_path }}

remove_follower_path

型：string

役割: フォロー解除するためのパスです。

{{ user.remove_follower_path }}

followers_json_url

型：string

役割: フォロワー情報（JSON）のURLです。

{{ user.followers_json_url }}

その他

attributes

型：object

役割: ユーザーの拡張項目です（動的な項目）。

{{ user.attributes.xxx }}

user_contents

型：list

{% for x in user.user_contents %}
  {{ x }}
{% endfor %}

user_articles

型：list

{% for x in user.user_articles %}
  {{ x }}
{% endfor %}

user_pages

型：list

{% for x in user.user_pages %}
  {{ x }}
{% endfor %}

メモ

articles など list系は for が基本です。
attributes は動的プロパティを持つため、基本形は {{ user.attributes.xxx }} です。

request

HTTPリクエスト情報（URL/パス/端末判定/クエリなど）です。

構造

request
├─ url（string）
├─ path（string）
├─ fullpath（string）
├─ params（hash）
├─ query_parameters（hash）
├─ current_page（integer）
├─ is_mobile（boolean）
├─ is_tablet（boolean）
└─ is_desktop（boolean）

型

単数

アクセス

{{ request.xxx }}

サンプルコード

URL

{{ request.url }}

パス

{{ request.path }}

クエリ（例: `q`）

{{ request.params["q"] }}

ページ番号（例: `page`）

{{ request.params["page"] }}

プロパティ一覧

基本

is_mobile

型：boolean

役割: モバイル端末からのアクセスかどうかを判定します。

{{ request.is_mobile }}

is_tablet

型：boolean

役割: タブレット端末からのアクセスかどうかを判定します。

{{ request.is_tablet }}

is_desktop

型：boolean

役割: デスクトップ端末相当のアクセスかどうかを判定します（is_mobile / is_tablet の否定です）。

{{ request.is_desktop }}

url

型：string

役割: リクエストURLです。

{{ request.url }}

path

型：string

役割: パス（クエリ除く）です。

{{ request.path }}

fullpath

型：string

役割: パス＋クエリ文字列を含むフルパスです。

{{ request.fullpath }}

params

型：hash

役割: パラメータ（クエリ・フォーム等を含む）にアクセスします。

{{ request.params["key"] }}

query_parameters

型：hash

役割: クエリ文字列のパラメータにアクセスします。

{{ request.query_parameters["key"] }}

current_page

型：string

役割: 現在ページ番号です（params["page"] から数字だけを取り出します）。

{{ request.current_page }}

メモ

params / query_parameters はキー指定で取り出すのが基本です。
端末判定は is_mobile / is_tablet / is_desktop を使います。
current_page は文字列です。数値として扱う場合は plus: 0 等で数値化してください。

paginate

ページネーション（分割表示）の状態です。
{% paginate ... %} の中で paginate として使います。

構造

paginate
├─ collection（list）
├─ page（integer）
├─ limit（integer）
└─ offset（integer）

型

単数

アクセス

{{ paginate.xxx }}

サンプルコード

記事一覧のページネーション（基本）

{% paginate site.articles per 10 %}
  {% selectfor (title, path) in paginate.collection %}
    {{ title }}
  {% endselectfor %}
{% endpaginate %}

現在ページ番号

{{ paginate.page }}

1ページあたり件数

{{ paginate.limit }}

オフセット

{{ paginate.offset }}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ paginate.cache_key }}

collection

型：list

役割: ページ分割した対象コレクション（現在ページ分）の一覧です。

{% for x in paginate.collection %}
  {{ x }}
{% endfor %}

page

型：integer

役割: 現在ページ番号です。

{{ paginate.page }}

limit

型：integer

役割: 1ページあたりの件数です。

{{ paginate.limit }}

offset

型：integer

役割: 取得開始位置（オフセット）です。

{{ paginate.offset }}

メモ

paginate は {% paginate %} ブロック内で使うのが基本です。
collection の要素型は元のlistによります。

comment

コメント（投稿）データです。
article.comments の for ループ内で使います。

構造

comment
├─ user（object: user）
├─ article（object: article）
├─ replies（list: comment）
├─ assets（list: comment_asset）
└─ new_reply_path（string）

型

単数

アクセス

{{ comment.xxx }}

サンプルコード

本文

{{ comment.body }}

投稿者名

{{ comment.user.name }}

返信一覧

{% for reply in comment.replies %}
  {{ reply.body }}
{% endfor %}

返信投稿リンク

返信する

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ comment.cache_key }}

sender

役割: 投稿者表示名（sender）です。
注意: ゲスト投稿の場合、ゲストが入力した表示名が入ります。

{{ comment.sender }}

id

型：integer

役割: コメントIDです。

{{ comment.id }}

user

型：object（user）

役割: コメント投稿者のユーザーです。

{{ comment.user.name }}

body

型：string

役割: コメント本文です。

{{ comment.body }}

article

型：object（article）

役割: コメント投稿元の記事です。

{{ comment.article.title }}

created_at

型：datetime

役割: コメントの作成日時です。

{{ comment.created_at }}

replies

型：list（comment）

役割: 返信コメントの一覧です。
注意: 実装上、作成日時の昇順（古い→新しい）で並びます。

{% for reply in comment.replies %}
  {{ reply.body }}
{% endfor %}

assets

型：list（comment_asset）

役割: コメント投稿時に添付されたファイル（添付）の一覧です。
注意: 各要素は comment_asset（コメント添付）です。

{% for asset in comment.assets %}
  {{ asset.original_url }}
{% endfor %}

new_reply_path

型：string

役割: 返信投稿ページへのパスです。

{{ comment.new_reply_path }}

メモ

replies はlistなので for が基本です。
assets もlistなので for が基本です。

collection

コレクション（まとめ）データです。
site.collections の for ループ内で使います。

構造

collection
└─ items（list: collection_item）

型

単数

アクセス

{{ collection.xxx }}

サンプルコード

ラベル

{{ collection.label }}

要素一覧

{% for ci in collection.items %}
  {{ ci.label }}
{% endfor %}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ collection.cache_key }}

name

型：string

役割: コレクション名です。

{{ collection.name }}

label

型：string

役割: ラベル（表示用の名称）です。

{{ collection.label }}

items

型：list（collection_item）

役割: コレクションに登録されている要素（collection_item）の一覧です。
注意: ループ変数名を item にすると、item オブジェクト（記事の本文中で使う item 等）と混ざって読みにくくなることがあります。必要に応じて ci 等に置き換えてください。

{% for ci in collection.items %}
  {{ ci.label }}
{% endfor %}

メモ

items はlistなので for が基本です。
各要素の詳細は collection_item（collection.items の要素）を参照してください。

collection_item

コレクション要素（collection.items の要素）データです。

構造

collection_item
├─ article（object: article）
└─ url / path / image_* ...（表示用フィールド）

型

単数

アクセス

※ このガイドでは、ループ変数名は item に統一します。

{{ item.xxx }}

サンプルコード

ラベル

{{ item.label }}

リンク

{{ item.label }}

画像（medium）

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ item.cache_key }}

type

役割: コレクション要素の種類（タイプ）を表す値です。

{{ item.type }}

label

型：string

役割: ラベル文字列です。

{{ item.label }}

caption

型：string

役割: キャプション（説明文）です。

{{ item.caption }}

optional_text

型：string

役割: 任意の補足テキストです。

{{ item.optional_text }}

url

型：string

役割: URL文字列です。

{{ item.url }}

path

型：string

役割: パス文字列です。

{{ item.path }}

画像

image_path

型：string

役割: 画像のパスです。

{{ item.image_path }}

image_url

型：string

役割: 画像のURLです。

{{ item.image_url }}

リレーション

article

型：object（article）

役割: 要素が記事のときの、記事オブジェクトです。

{{ item.article.title }}

メモ

collection.items の各要素がこのオブジェクトです。

comment_asset

コメント添付（comment.assets の要素）データです。

構造

comment_asset
└─ *_url（画像URL系）

型

単数

アクセス

※ このガイドでは、ループ変数名は asset に統一します。

{{ asset.xxx }}

サンプルコード

原寸URL

{{ asset.original_url }}

サムネURL

{{ asset.thumbnail_url }}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ asset.cache_key }}

画像

small_url

型：string

役割: 横幅320pxにリサイズされた画像のURLです。

{{ asset.small_url }}

medium_url

型：string

役割: 横幅640pxにリサイズされた画像のURLです。

{{ asset.medium_url }}

large_url

型：string

役割: 横幅1280pxにリサイズされた画像のURLです。

{{ asset.large_url }}

square_url

型：string

役割: 高さ・横幅150pxの正方形にリサイズされた画像のURLです。

{{ asset.square_url }}

thumbnail_url

型：string

役割: 高さ・横幅75pxの正方形にリサイズされた画像のURLです。

{{ asset.thumbnail_url }}

original_url

型：string

役割: オリジナルサイズの画像のURLです。
注意: original_url はオリジナル画像のURLです。使用時は resize フィルタの併用を推奨します。

{{ asset.original_url }}

メモ

画像サイズは用途に応じて small_url / medium_url / large_url などを選びます。

gallery

ギャラリー（画像セット等）データです。
item.galleries の for ループ内で使います。

構造

gallery
└─ url / source / image_* ...（表示用フィールド）

型

単数

アクセス

{{ gallery.xxx }}

サンプルコード

タイトル

{{ gallery.title }}

画像（medium）

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ gallery.cache_key }}

url

型：string

役割: URL文字列です。

{{ gallery.url }}

source

型：string

役割: 出典（source）文字列です。

{{ gallery.source }}

source_url

型：string

役割: 出典URL（source URL）文字列です。

{{ gallery.source_url }}

title

型：string

役割: 画像タイトルです。

{{ gallery.title }}

comment

型：string

役割: コメント（補足）です。

{{ gallery.comment }}

画像

画像サイズ

image_original_width

型：integer

役割: オリジナル画像の横幅（px）です。

{{ gallery.image_original_width }}

image_original_height

型：integer

役割: オリジナル画像の高さ（px）です。

{{ gallery.image_original_height }}

image_large_width

型：integer

役割: large（例: 1280px）サイズ画像の横幅（px）です。

{{ gallery.image_large_width }}

image_large_height

型：integer

役割: large（例: 1280px）サイズ画像の高さ（px）です。

{{ gallery.image_large_height }}

image_medium_width

型：integer

役割: medium（例: 640px）サイズ画像の横幅（px）です。

{{ gallery.image_medium_width }}

image_medium_height

型：integer

役割: medium（例: 640px）サイズ画像の高さ（px）です。

{{ gallery.image_medium_height }}

image_small_width

型：integer

役割: small（例: 320px）サイズ画像の横幅（px）です。

{{ gallery.image_small_width }}

image_small_height

型：integer

役割: small（例: 320px）サイズ画像の高さ（px）です。

{{ gallery.image_small_height }}

image_square_width

型：integer

役割: square（例: 150px 正方形）サイズ画像の横幅（px）です。

{{ gallery.image_square_width }}

image_square_height

型：integer

役割: square（例: 150px 正方形）サイズ画像の高さ（px）です。

{{ gallery.image_square_height }}

image_thumbnail_width

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の横幅（px）です。

{{ gallery.image_thumbnail_width }}

image_thumbnail_height

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の高さ（px）です。

{{ gallery.image_thumbnail_height }}

その他

domain

型：string

役割: ドメイン文字列です。

{{ gallery.domain }}

メモ

画像サイズは用途に応じて image_small_url / image_medium_url / image_large_url などを選びます。

item_asset

アイテムの画像・ファイル等のアセットデータです。（記事本文アイテムが持つ画像URL群とは別系統の“アセット表現”として扱います）

構造

item_asset
└─ *_url / file_* ...（URL・ファイル情報）

型

単数

アクセス

※ このガイドでは、ループ変数名は asset に統一します。

{{ asset.xxx }}

サンプルコード

原寸URL

{{ asset.original_url }}

サムネURL

{{ asset.thumbnail_url }}

ファイルURL

{{ asset.file_url }}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ asset.cache_key }}

画像

small_url

型：string

役割: 横幅320pxにリサイズされた画像のURLです。

{{ asset.small_url }}

medium_url

型：string

役割: 横幅640pxにリサイズされた画像のURLです。

{{ asset.medium_url }}

large_url

型：string

役割: 横幅1280pxにリサイズされた画像のURLです。

{{ asset.large_url }}

square_url

型：string

役割: 高さ・横幅150pxの正方形にリサイズされた画像のURLです。

{{ asset.square_url }}

thumbnail_url

型：string

役割: 高さ・横幅75pxの正方形にリサイズされた画像のURLです。

{{ asset.thumbnail_url }}

original_url

型：string

役割: オリジナルサイズの画像のURLです。
注意: original_url はオリジナル画像のURLです。使用時は resize フィルタの併用を推奨します。

{{ asset.original_url }}

画像サイズ

original_width

型：integer

役割: オリジナル画像の横幅（px）です。

{{ asset.original_width }}

original_height

型：integer

役割: オリジナル画像の高さ（px）です。

{{ asset.original_height }}

large_width

型：integer

役割: large（例: 1280px）サイズ画像の横幅（px）です。

{{ asset.large_width }}

large_height

型：integer

役割: large（例: 1280px）サイズ画像の高さ（px）です。

{{ asset.large_height }}

medium_width

型：integer

役割: medium（例: 640px）サイズ画像の横幅（px）です。

{{ asset.medium_width }}

medium_height

型：integer

役割: medium（例: 640px）サイズ画像の高さ（px）です。

{{ asset.medium_height }}

small_width

型：integer

役割: small（例: 320px）サイズ画像の横幅（px）です。

{{ asset.small_width }}

small_height

型：integer

役割: small（例: 320px）サイズ画像の高さ（px）です。

{{ asset.small_height }}

square_width

型：integer

役割: square（例: 150px 正方形）サイズ画像の横幅（px）です。

{{ asset.square_width }}

square_height

型：integer

役割: square（例: 150px 正方形）サイズ画像の高さ（px）です。

{{ asset.square_height }}

thumbnail_width

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の横幅（px）です。

{{ asset.thumbnail_width }}

thumbnail_height

型：integer

役割: thumbnail（例: 75px 正方形）サイズ画像の高さ（px）です。

{{ asset.thumbnail_height }}

ファイル

file_name

型：string

役割: 添付ファイル名です。

{{ asset.file_name }}

file_content_type

型：string

役割: 添付ファイルのMIMEタイプです。

{{ asset.file_content_type }}

file_size

型：integer

役割: 添付ファイルのサイズ（バイト）です。

{{ asset.file_size }}

file_url

型：string

役割: 添付ファイルのURLです。

{{ asset.file_url }}

file_download

型：string

役割: 添付ファイルのダウンロード用パスです。

{{ asset.file_download }}

メモ

画像サイズは用途に応じて small_url / medium_url / large_url などを選びます。

form

フォーム（設問・ダウンロード導線など）データです。

構造

form
├─ files（list）
└─ url / title / description ...（基本フィールド）

型

単数

アクセス

{{ form.xxx }}

サンプルコード

タイトル

{{ form.title }}

フォームURL

{{ form.title }}

添付ファイル一覧（例）

{% for file in form.files %}
  {{ file }}
{% endfor %}

プロパティ一覧

基本

is_downloadable

型：boolean

役割: ダウンロード可能な添付ファイルを持つかどうかを表します。

{{ form.is_downloadable }}

files

型：list

役割: ダウンロード可能な添付ファイル一覧です。

{% for file in form.files %}
  {{ file }}
{% endfor %}

download_page_url

型：string

役割: ダウンロードページのURLです。

{{ form.download_page_url }}

url

型：string

役割: フォームのURLです。

{{ form.url }}

title

型：string

役割: フォームのタイトルです。

{{ form.title }}

description

型：string

役割: フォームの説明文です。

{{ form.description }}

メモ

files はlistなので for が基本です。

form_reply

フォーム回答（送信結果）データです。

構造

form_reply
├─ user（object: user）
├─ form（object: form）
├─ values（list: form_reply_value）
└─ download_page_url（string）

型

単数

アクセス

※ このガイドでは、ループ変数名は reply に統一します。

{{ reply.xxx }}

サンプルコード

ダウンロードページURL

{{ reply.download_page_url }}

回答値一覧

{% for value in reply.values %}
  {{ value.name }}: {{ value.value }}
{% endfor %}

プロパティ一覧

基本

user

型：object（user）

役割: 回答者のユーザー情報です（ログインして回答するフォームの場合に入ります）。

{{ reply.user.name }}

form

型：object（form）

役割: 元のフォーム情報です。

{{ reply.form.title }}

values

型：list（form_reply_value）

役割: 回答値の一覧です。実装上、HTML表示専用・ファイル型の設問は除外されます。

{% for value in reply.values %}
  {{ value.name }}
{% endfor %}

download_page_url

型：string

役割: ダウンロードページのURLです（フォームの種類により利用します）。

{{ reply.download_page_url }}

メモ

values はlistなので for が基本です。

form_reply_value

フォーム回答の 1フィールド分の値データです。 reply.values の for ループ内で使います。

構造

form_reply_value
├─ name（string）
├─ value
└─ type

型

単数

アクセス

※ このガイドでは、ループ変数名は value に統一します。

{{ value.xxx }}

サンプルコード

フィールド名と値

{{ value.name }}: {{ value.value }}

プロパティ一覧

基本

name

型：string

役割: フィールド名（設問の表示名）です。

{{ value.name }}

value

役割: 回答値です（型はフォーム定義により変わります）。

{{ value.value }}

type

役割: フィールドの種別（フォーム定義の型名）です。

{{ value.type }}

メモ

value / type の中身はフォーム定義によります。

controller

コントローラ系のテンプレート向け情報（ログイン状態・パンくず等）です。
テンプレートによっては controller として参照されます。

構造

controller
├─ current_user（object: user）
├─ signed_in（boolean）
├─ render_breadcrumbs
├─ smart_phone?（boolean）
├─ breadcrumbs
└─ response_status

型

単数

アクセス

{{ controller.xxx }}

サンプルコード

ログインしているか

{{ controller.signed_in }}

現在ユーザー名

{{ controller.current_user.name }}

スマホ判定

{{ controller.smart_phone? }}

プロパティ一覧

基本

current_user

型：object（user）

役割: 閲覧者（ログイン中ユーザー）のユーザー情報です。

{{ controller.current_user.name }}

signed_in

型：boolean

役割: 閲覧者がログインしているかどうかを表します。

{{ controller.signed_in }}

render_breadcrumbs

役割: パンくずリスト（HTML）を出力します。

{{ controller.render_breadcrumbs }}

smart_phone?

型：boolean

役割: スマホ相当かどうかを判定します（互換用）。
注意: 実装上、非推奨です。端末判定は request.is_mobile の利用を推奨します。

{{ controller.smart_phone? }}

breadcrumbs

役割: パンくずの要素一覧です（中身は画面文脈に依存します）。

{{ controller.breadcrumbs }}

response_status

役割: HTTPステータスコードです。

{{ controller.response_status }}

メモ

distributor

配信元（ディストリビュータ）データです。

構造

distributor
└─ name / label / url / image_* ...（基本フィールド）

型

単数

アクセス

{{ distributor.xxx }}

サンプルコード

表示名

{{ distributor.name }}

URL

{{ distributor.label }}

画像URL

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ distributor.cache_key }}

name

型：string

役割: 配信元（RSS受信元等）のサイト名です。

{{ distributor.name }}

label

型：string

役割: 配信元の識別子（英数字ラベル）です。

{{ distributor.label }}

url

型：string

役割: 配信元のURLです。

{{ distributor.url }}

画像

image_path

型：string

役割: 配信元に設定したアイコン画像のパスです。

{{ distributor.image_path }}

image_url

型：string

役割: 配信元に設定したアイコン画像のURLです。

{{ distributor.image_url }}

メモ

static_page

固定ページ（静的ページ）データです。
site.pages / category.pages の for ループ内で使います。

構造

static_page
└─ name / title ...（基本フィールド）

型

単数

アクセス

※ このガイドでは、ループ変数名は page に統一します。

{{ page.xxx }}

サンプルコード

タイトル

{{ page.title }}

名前

{{ page.name }}

プロパティ一覧

基本

cache_key

型：string

役割: キャッシュ用のキーです。

{{ page.cache_key }}

name

型：string

役割: 固定ページの識別名です。

{{ page.name }}

title

型：string

役割: 固定ページのタイトルです。

{{ page.title }}

メモ

ループ変数名は page を使います。

additional_field

拡張項目の定義（フォームや記事の拡張項目の定義用）データです。

構造

additional_field
├─ name（string）
├─ type
└─ options

型

単数

アクセス

※ このガイドでは、ループ変数名は field に統一します。

{{ field.xxx }}

サンプルコード

フィールド名

{{ field.name }}

型

{{ field.type }}

プロパティ一覧

基本

name

型：string

役割: 拡張項目名（表示名）です。

{{ field.name }}

type

役割: 拡張項目の種別です。
注意: 実装上、type は「種別名」を返す想定ですが、環境によっては期待どおりでない場合があります。困ったときは options とあわせて確認してください。

{{ field.type }}

options

役割: 選択肢等のオプション一覧です（list）。

{{ field.options }}

メモ

options の形はフィールド種別によります。

article_attributes

記事の拡張項目（動的フィールド）です。
article.attributes として参照します。

構造

article
└─ attributes（object: article_attributes）

型

単数

アクセス

{{ article.attributes.xxx }}

サンプルコード

フィールド（例）

{{ article.attributes.some_field }}

画像系サフィックス（例）

※ フィールドが画像の場合、{{ article.attributes.some_field }} のようにサイズなしでは取得できません（実装上、案内文が返ります）。

{{ article.attributes.some_field_medium_url }}

プロパティ一覧

基本

liquid_method_missing(method)

メソッド名（フィールド名）で参照できます（利用できるキーはサイト設定で決まります）。

役割: 記事の拡張項目の値を取り出します。
注意: 画像フィールドはサイズサフィックス必須です（例: _small / _medium / _large / _square / _thumbnail / _original）。
注意: _original（オリジナル）を使う場合は resize フィルタの併用を推奨します。

{{ article.attributes.xxx }}

対応サフィックス:

xxx_(small|medium|large|square|thumbnail|original)

メモ

動的Dropのため、利用可能なキーはサイト設定によります。
画像系は _small_url のようなサフィックス付きでアクセスするパターンがあります。

article_favorites

記事のお気に入り系（動的フィールド）です。
article.favorites として参照します。

構造

article
└─ favorites（object: article_favorites）

型

単数

アクセス

{{ article.favorites.xxx }}

サンプルコード

数値フィールド（例: `num_xxx`）

{{ article.favorites.num_xxx }}

プロパティ一覧

基本

liquid_method_missing(method)

メソッド名で参照できます（利用できるキーはサイト設定で決まります）。

役割: お気に入り種別ごとの件数を取得します（num_ 形式のみ対応します）。
注意: num_ 以外のキーは参照できません。

{{ article.favorites.xxx }}

表記:

num_xxx 形式

メモ

動的Dropのため、利用可能なキーはサイト設定によります。
典型形は {{ article.favorites.num_ }} です。

user_attributes

ユーザーの拡張項目（動的フィールド）です。
user.attributes として参照します。

構造

user
└─ attributes（object: user_attributes）

型

単数

アクセス

{{ user.attributes.xxx }}

サンプルコード

フィールド（例）

{{ user.attributes.some_field }}

※ フィールド名が日本語の場合、ドット記法では参照できないことがあります。その場合は [] 記法を使います。

{{ user.attributes["性別"] }}

明示検索（例）

{{ user.attributes.find_attribute_value("some_field") }}

プロパティ一覧

基本

liquid_method_missing(method)

メソッド名（フィールド名）で参照できます（利用できるキーはサイト設定で決まります）。

役割: ユーザーの拡張項目の値を取り出します。
注意: フィールド名が日本語の場合は [] 記法の利用を推奨します（例: user.attributes["性別"]）。

{{ user.attributes.xxx }}

find_attribute_value(field_name)

役割: フィールド名を文字列で指定して値を取り出します（主に動的にフィールド名を組み立てる場合に使います）。

{{ user.attributes.find_attribute_value("field_name") }}

メモ

動的Dropのため、利用可能なキーはサイト設定によります。
find_attribute_value はユーザーの拡張項目のAPIです（article.attributes とは別物です）。

フィルタ（拡張）

導入

この章は、テンプレート上で、一覧を絞る／並べる／件数を減らす／文字を整えるためのフィルタを調べるリファレンスです。迷ったら大見出し（第2見出し）の分類から入り、小見出し（第3見出し）の例を出発点にしてください。

誰向けか

Clipkit のテンプレートを、管理画面等で編集・保守する担当者向けを主の読者とします。

扱う範囲

ここに載せるのは、Clipkit が追加で用意した拡張フィルタだけです。多くの環境に共通する標準の Liquid フィルタの全件を、ここで解説し切る章ではありません。{{ … }} で値を出す区切りと、{% … %} で命令を書く区切りの違いは、利用中の管理画面の案内、または一般向けの Liquid 入門で先に押さえてから本章を開くと、迷いにくいです。
正規表現や、日付の細かい表記、条件式の専門的な書き方そのものの学習は、本章の主題外です。必要に応じて専門書を当たってください。

フィルタは何のための部品か

フィルタは、いま扱っている値に、次の一歩（絞り込み、並べ替え、件数の制限、表記の変換など）を加えるための、英名の部品です。テンプレート言語（Liquid）では、値の右に |（縦棒）を書き、その右にフィルタ名（と、必要なら追加の指定）を続けます。縦棒の左の結果が、一つ右の部品の入力になっていきます。例として、記事の一覧を公開日の新しい順にそろえ、その先頭 5 件だけ残す、といった要望を、縦棒でつないで表現します。

本文で繰り返す三語

繰り返しを減らすため、次の三語にそろえて記述します。

元の値: 縦棒の左にあり、当該フィルタに入る直前のデータ（例: 記事の一覧、1 行の文字列）を指す。
第2 引数、第3 引数…: | の後に フィルタ名: 値1, 値2, … とした場合、元の値を第1 引数、値1 を第2 引数、値2 を第3 引数と数える。定義はフィルタごとに異なる。
結果: 当該フィルタの一段をかけたあとに得られる値。挙動の詳細は、管理画面のプレビューで確認する。

用語の意味がはっきりしなければ、同じ小見出しの例を出発点に、条件を一つずつ変えてプレビューで確かめてください。

前提

縦棒の直前（左）に書いてある内容が、元の値です。
複数件のデータ（一覧）は、1 か所の {{ }} だけに詰め込まず、多くの場合 for（同じ形の行を、件数分くり返す）で行やブロックに分けて表示します。
order や limit は縦棒でつなぎ、必要なら assign（いったん変数の名前に入れる）してから for します。

各節の読み方

各フィルタ（小見出し。英名のとおり、テンプレートにその英名を書きます）の下は、だいたい次の行の順です。役割（何のための部品か）→ 元の値（左に来る想定）→ 引数（右で足す指定）→ 結果（かけたあとに出る中身）→ 例（まねしやすい形）→ 注意（失敗のおそれや非推奨。該当するときだけ）。表は使いません。

英名の意味を覚えなくても、やりたい作業（一覧を絞る、並べ替える、件数を減らす、文章の表記を直すなど）に近い大見出し（第2見出し）からざっと入り、当たりの小見出し（第3見出し）の例の中身だけ差し替え、プレビューで意図どおりか確かめてください。

一覧の絞り込み・並べ替え

`where`

役割: 条件付きで一覧を絞り込む。
元の値: 主に site.articles のように、条件で絞り込める記事の一覧から始めます。
引数: 第2 に条件の文字、第3 以降に、条件中の ? に当てはめる値。複雑な指定を避ける場合は、第3 に名と値の多くの組がいっしょに来る形では、where には limit などだけ付け、where のあと、別の縦棒で | limit や | order を続ける書き方を推奨します。
結果: 絞り込んだあとも、一覧として扱えます（そのまま for へ）。
例:

{% assign a = site.articles | where: "category_id = ?", category.id %}

`find_by`

役割: 1件取得。
引数: 第2 に項目名、第3 に条件に合わせる値（たとえば id と 123）。
結果: 1件。見つからない場合は空。
例:

{% assign article = site.articles | find_by: "key", "xxxxx" %}

`limit`

役割: 先頭から指定件数分だけを残し、それ以降を除く。要素が複数ある一覧に対しては、先頭から指定件数分の要素からなる列が得られる。
引数: 第2: 件数（非負整数を想定）。
結果: 第2 引数の件数を上限に、元の一覧の先頭からそこまでの分だけ残した一覧。前段のフィルタと同じつながりで for へ回せることが多い（利用環境の挙動に従う）。
例: 他のフィルタのあと次のように使う。ループ前に assign してから for する例は多い。

{% assign recent = site.articles | order: "published_at DESC" | limit: 5 %}
{% selectfor (title, url) in recent %}
  {{ title }}
{% endselectfor %}

`order`

役割: 並び順を付与する。列名の表記は、意図しない解釈を避けるよう正規化される。
引数: 第2: ソート文字列（例: published_at DESC）。
結果: 一覧として扱える結果。
例:

{% assign articles = site.articles | order: "published_at ASC" %}

`offset`

役割: 先頭から指定件数分を除き、残りを得る。要素が複数ある一覧に対しては、先頭 N 要素を除いた列になる（N は第2 引数）。
引数: 第2: 捨てる件数。
例:

{% assign articles = site.articles | offset: 5 %}

`or`（非推奨）

役割: 二つの一覧の論理和（OR）として結合する。関係の結合制約により使用できない場合がある。
利用上の推奨は union です。or は非推奨です（既存テンプレートとの互換のため残します）。
例:

{% assign articles_m  = site.articles | search: 'category:"male"' %}
{% assign articles_f = site.articles | search: 'category:"female"' %}
{% assign articles = articles_m | or: articles_f %}

`union`

役割: 同種の二つの一覧の重複を除き、一つにまとめる。内側に付与した order は、結合前に解釈上破棄される。詳細は稼働環境の挙動をプレビューで確認する。
引数: 第2: もう一方の、同じ種類の一覧。
結果: まとめ直した一つの一覧。
例:

{% assign part_a = site.articles | search: "tag:foo" %}
{% assign part_b = site.articles | search: "tag:bar" %}
{% assign combined = part_a | union: part_b %}

`next_to` / `prev_to`

役割: 同カテゴリ等の並びの隣接記事。
引数: 第2: 比較の基準とする article。
結果: 1件の記事です。見つからない場合は空です。比較の基準として第2に指定するのは記事です。記事以外の値にした場合、結果が空になる、または案内用の表示が出るなど、意図した表示にならないことがあります（利用環境に従います）。
例:

{% assign next_article = article.category.articles | next_to: article %}
{% assign prev_article = article.category.articles | prev_to: article %}

`size`

役割: 件数。
結果: 非負整数です。列挙可能な要素の件数です。1件もない場合の結果は 0 です。
例:

{% assign articles_size = site.articles | size %}
{% if articles_size > 0 %}
  
{% endif %}

`to_array` / `to_a`

役割: テンプレート上で for による反復に使う形に変換する。件数に上限のある記事一覧等（サイト設定に依存）をその形に整える場合、取得件数の上限（多くの構成でおおむね 200 件前後。正確な数は稼働環境の挙動に従う。件数に関する注意は当章「安全と非推奨」に示す）が適用される。
結果: 反復に使える列。for で要素にアクセスできる。
例:

{% assign pref_array = site.articles | search: 'category:"prefecture"' | to_array %}

`type`

役割: デバッグのため、オブジェクトの型を示す識別子名を文字列で返す。本番の公開画面では、必要箇所に限り用いる。
結果: 文字列。
例:

{{ site.articles | type }}
{{ article.title | type }}

`select`

役割: 列指定の文字列で表示に必要な列に絞る。記事の一覧想定。
引数: 第2: 例 'title, user, category, attribute:会場'
結果: 必要な項目だけ抜かれた、記事の一覧。
例:

{% assign slim = site.articles | select: "title, user, category, attribute:会場" %}

検索

`search`

役割: 全文検索の条件に合致する記事一覧を返す。関連データの事前読み込み等の挙動は、稼働環境の実装に従う。
引数: 第2: 問い合わせ文字列。
結果: 検索後、一覧として扱える結果。
例:

{% assign found = site.articles | search: request.params["q"] %}

拡張項目

`attribute`

役割: 記事またはユーザーの拡張項目名から値を出す。画像キー等の表記の規則は、サイトの設定に従う。
元の値: 記事またはユーザーのオブジェクト。
引数: 第2: 拡張項目名（文字列）。
例:

{{ article | attribute: "area" }}

同じ拡張項目へは、拡張項目名をドットで辿る書き方でも触れられます。例: 拡張項目名が venue のとき {{ article.attributes.venue }}。

`search_by_attribute`

役割: 拡張項目の名と、探したい値で、記事やユーザーの一覧に絞ります。左に渡すのが記事なのかユーザーなのかで、どちらの一覧から探すかが分かれます。
引数: 第2: 拡張項目名。第3: 比べる値。第4: 比べ方（省略のときは「等しさ」のよく使う形）。
例:

{% assign articles = site.articles | search_by_attribute: "area", "kanto", "= ?" %}

`order_by_attribute`

役割: 拡張項目の値で並べ替えます。昇順・降順は第3引数で指定し、省略したときは昇順になります。
引数: 第2: 名。第3: 昇順 / 降順。
例:

{% assign sorted = site.articles | order_by_attribute: "score", "DESC" %}

文字列・HTML

`raw`

役割: 文字列化し、自動エスケープの対象外の HTML 向け扱いにする。
結果: その扱いの付いた文字列。
例（出所を把握した HTML のみ。不特定の入力に対して常時使わない）:

{{ trusted_html_from_admin | raw }}

`auto_link`

役割: 文中の URL 文字列を、サイト設定のリンク方針に従いへ変換。

元の値: 文字列。

例:

{% assign sample_txt = "公式サイトはhttps://clipkit.coです。" %}
{{ sample_txt | auto_link }}

`render_markdown` / `render_liquid`

役割: 前者は Markdown から HTML 等へ変換する。後者は別文脈で文字列を Liquid として再解釈する。挙動の詳細はプレビューで検証する。
結果: 文字列。render_markdown では、多くの場合、表示用の HTML 断片（タグを含む）を返す。render_liquid は、評価の結果として得られた文字列を返す。中身に HTML のタグが入るかどうかは、テンプレートに書いた内容による。
例:

{% assign heading_template = "{{ category.name }}の記事まとめ" %}
{{ heading_template | render_liquid }}

{% assign markdown_text = "お知らせ" %}
{{ markdown_text | render_markdown }}

`unescape`

役割: エンコード済みの HTML 実体を人が読む文字列に戻す。
例:

{% assign text = "Tom & Jerry" %}
{{ text | unescape }}

`wpautop`

役割: 段落付け。失敗時は元の文字列。
例:

{% assign body = "これは1段落目です。\n\nこれは2段落目です。" %}
{{ body | wpautop }}

`replace_regexp` / `match` / `regexp_escape`

replace_regexp: 与えた正規表現で置換。時間切れ等は元の文字列のまま。
match: 正規表現の有無に合わせ、一致有無。時間切れ等は合わない扱い。
regexp_escape: 正規表現用に文字列を安全にエスケープ。

例（置換と一致）:

{% assign tag = "#ニュース" %}
{{ tag | replace_regexp: "^#", "" }}

{% assign email = "user@example.com" %}
{% if email | match: "^[\\w._%+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$" %}
  有効なメール形式です
{% else %}
  形式を確認してください
{% endif %}

regexp_escape（利用者入力を正規表現内に差し込む前など）:

{{ user_keyword | regexp_escape }}

マップ・配列

`hash_find`

役割: 並んだ要素のなかから、指定したキーと値の組が合う最初の1件を取り出します。GraphQL など、階層の深いデータから得た一覧にも使います。
結果: 入力が空のときは空のマップを返す。キーと値の組に一致する要素がなければ空。一致すれば最初の1件。入れ子の構造は、利用するデータソースの定義に従う。
例:

{% assign collection = graphql_response.data.mainPage.collections | hash_find: "namespace", "ranking" %}
{{ collection.title }}

`to_hash`

役割: 1本の JSON 形式の文字列を、テンプレート内で扱いやすい、入れ子のマップや配列の形に直します。
結果: 解釈できない場合は空のマップ。
例（json_parse も同じ json_string で次のとおり）:

{{ json_string | json_parse }}
{{ json_string | to_hash }}

json_parse と to_hash の厳密な違いは、利用している環境で確かめ、下の json_parse の説明と併せて使い分けてください。

`headings_per_page`

役割: 記事本文ブロックから見出しを抽出し、タイトル、パス、階層等の一覧を返す。リクエスト文脈および記事オブジェクトの有無により結果は変化する。詳細は表示環境で検証する。
引数: 第2: 1 ページ相当の行数を表す整数。省略可。省略時はサイトの既定の 1 ページあたり件数に従う。
例:

{% assign headings = article.items | headings_per_page: 15 %}
{% for heading in headings %}
  {{ heading.text }}
{% endfor %}

JSON ・数値

`to_json`

役割: JavaScript など、外部のプログラムに渡しやすいよう、JSON 形式の一続きの文字にします。
結果: 1 本の文字列（JSON テキスト）。
例:

`json_parse`

役割: JSON 形式の文字列を、テンプレート上で扱いやすい入れ子のマップや配列の形に戻します。解釈に失敗したあとの扱いは、そのテンプレートの方針に従います。
結果: マップ、配列、など。内容は渡した文字列次第です。
例: 上の to_hash 節に出てくる、同じ json_string の行を、ここでも用います（json_parse と to_hash のブロックの両方に、同じ例を載せています）。

`format_number`

役割: 金額表示のように、3 桁ごとに区切る（カンマをはさむ）形の文字列にします。日本語を含む数字の見せ方にも配慮した挙動です。
例:

{% assign price = "123456789" %}
¥{{ price | format_number }}

パス・URL

`prepend_path`

役割: 元の文字列が絶対 URL（http / https）の場合、ホスト部以降に第2 引数のパスを挿入する。相対 URL の場合はパス結合に相当する。第2 引数が空の場合は、元の文字列を変更せず返す。
例:

{{ tag.path | prepend_path: category.path }}

`find_path`

役割: 第2 引数のパス（タグ階層またはカテゴリ階層）に一致する要素を、元の値の集合（all_tags 等）から取得する。該当がなければ、空（要素なし）を返す。
引数: 第2: 探すパス（/ から始めてもよい。tags/ で始まるとタグ向け、といった慣習に従います）。
例:

{% assign tag = site.all_tags | find_path: "/tags/tech/html" %}
{{ tag.name }}

{% assign category = site.all_categories | find_path: "/travel/japan/kyoto" %}
{{ category.name }}

`filename`

引数（第2）: サイトに登録されたファイルを、パスで指定します。どの一覧が左に来るかは、利用している画面や設定に依存します。
例（左に渡すオブジェクト名は、利用環境に従います）:

{{ site.files | filename: "/path/example.jpg" }}

`resize`

役割: 画像の元の URL のあとに、幅・高さなどの条件を、クエリ（アドレスの ? 以降）に付け足します。"width:320" のように、幅や高さを : で区切って書きます。
例:

{{ item.image_original_url | resize: "width:320" }}

{{ item.image_original_url | resize: "width:320,height:320" }}

{{ item.image_original_url | resize: "size:320" }}

注意: width / height / size には 1200 を超える数値を指定できない。超過、または元画像の不整合がある場合は、元解像度の画像が返却される。表示の寸法は、CSS により制御する。

`cv_url`

役割: アクセス計測用に、記事 URL を計測用の中継 URL へ変換して返す。リクエストの文脈（URL、クエリ、サイト名等）に依存し、条件が揃わない場合は有効化できない。
例:

{{ article.url | cv_url }}

日付

`date`

役割: 日付を、指定した書式文字列に従い文字列化する。Clipkit では、書式文字列中の %H:%m を %H:%M へ正すなど、誤りやすい月・分の指定を補正する拡張を有する。
引数: 第2: 表示の形を決める文字列（年・月・日・時・分の並び。よく使う「書式のパターン」に従います）。
例:


  {{ article.published_at | date: "%Y年%m月%d日 %H:%M" }}

よく使う連鎖

並びと件数: order ののち limit、必要なら for。

{% assign list = site.articles | order: "published_at DESC" | limit: 10 %}
{% selectfor (title, url) in list %}
  {{ title }}
{% endselectfor %}

条件: where のあと for。? にどの値を当てるかは、上の where の例と同じ考え方です。

{% assign list = site.articles | where: "category_id = ?", category.id %}
{% selectfor (title, url) in list %}
  
{% endselectfor %}

本文を HTML 化: 出所の信頼性に注意。

{{ article.description | render_markdown }}

安全と非推奨

where や search の条件文を、訪問者の入力を文字どおりつなぎ足すだけで組み立てない。? に値を差し込む形にする、使ってよい列名はホワイトリストで絞る、などの方針は、サイト運用の側で決める。
or は原則使わず、先に union や、条件の書き方の見直しを検討する。
to_a 系: 件数に制限のある一覧から配列化した際、取得件数の上限（多くの環境でおおむね 200 件前後。上限の正確な値は稼働環境の挙動に従う）により切り詰められる。必要件数を満たすかは、プレビューで検証する。
raw や、同様に「信頼してよい」とみなされるフィルタ: 出所の分からない訪問者の入力に、常に raw をかけない。管理画面で入れたHTMLなど、信頼できる出所の内容に限る。

タグ（制御・部品）

導入

この章は、Liquid の {% %} 形式で記述する「タグ」（条件分岐・繰り返し・Clipkit 拡張の部品）を、必要なときに引けるリファレンスとしてまとめます。
値の出力（{{ }}）と異なり、タグはテンプレートの流れ（条件分岐・反復）や、サイト機能の部品の呼び出しを担います。

誰向けか

Clipkit のテーマ（テンプレート）を編集し、一覧表示・詳細表示・部品の差し替えを行う担当者向けです。

扱う範囲

ここでは、標準 Liquid の代表的な制御タグと、Clipkit 拡張タグの最小例を扱います。
標準 Liquid のタグを、網羅的に解説し切る章ではありません。必要に応じて外部の一次情報を参照してください。
各オブジェクト（site / article など）のプロパティや関係は、第2章のリファレンスを参照してください。

本文で繰り返す語

記述の揺れを避けるため、次の語を用います。

構文: テンプレートに書くタグの形（例: {% if ... %}...{% endif %}）。
ブロック: 開始タグと終了タグで囲まれた範囲（例: {% paginate ... %} 〜 {% endpaginate %}）。
引数: タグ名の後ろに続く指定（例: {% render "card", article: article %} の "card" や article: article）。
結果: 出力の有無や、テンプレートの変数・文脈に生じる変化（例: paginate により paginate.collection が使える、など）。

前提：`{{ }}` と `{% %}`

{{ }} は値を出力します（必要に応じてフィルタ | で加工できます）。
{% %} は制御します（条件分岐・反復・変数代入・Clipkit の部品呼び出し等）。

{{ site.title }}

{% if site.title != blank %}
  タイトルあり
{% endif %}

各節の読み方

本章の各タグ（小見出し（第3見出し））では、原則として次の順で示します。

役割（何のために使うか）
構文（最小の形）
引数（必要な場合のみ）
結果（テンプレート上で何が起きるか）
例（まねしやすい形）
注意（失敗しやすい点がある場合のみ）

分類（どこから探すか）

条件分岐: if / elsif / else
反復: for / paginate / selectfor
変数の用意: assign / capture
部品の呼び出し: render / collection / form
キャッシュ: cache
同意に応じた表示: consent
ファイル・スクリプトの読み込み: file / javascript_pack_tag

標準 Liquid の代表的な制御タグ

`assign`

役割: 値に名前を付け、後続の処理で再利用できるようにする。
構文:

{% assign articles = site.articles | limit: 5 %}

`if` / `elsif` / `else`

役割: 条件によって表示を分ける。
構文（最小）:
結果: 条件が真のときだけ、ブロック内を出力します。

{% if article.title != blank %}
  {{ article.title }}
{% endif %}

`for`

役割: 一覧を要素ごとに反復して表示する。
構文（最小）:
結果: 一覧の要素数だけ、ブロック内が繰り返し出力されます。

{% for article in site.articles %}
  {{ article.title }}
{% endfor %}

selectfor の例（記事一覧を高速に展開したい場合）:

{% selectfor (title) in site.articles %}
  {{ title }}
{% endselectfor %}

`capture`

役割: ある範囲の出力結果を文字列として変数に保持する。
構文（最小）:
結果: ブロック内の出力が文字列になり、指定した変数名に入ります。

{% capture heading %}
  {{ category.name }}の記事まとめ
{% endcapture %}
{{ heading }}

Clipkit 拡張タグ

この節は、挙動の把握に足る例に限って示します。
タグによって追加の引数があるものもあり、その可否や意味はサイトやテーマの構成によって差が出る場合があります。必要に応じて、利用中のサイトのテンプレート内の用例とプレビューで確認してください。

`paginate`

役割: 一覧をページ分割し、ページ内のコレクションやページ情報を扱う。
構文:
結果: ブロック内で paginate が使えるようになります。反復対象は paginate.collection を用います。

{% paginate site.articles per 10 %}
  {% selectfor (title) in paginate.collection %}
    {{ title }}
  {% endselectfor %}
{% endpaginate %}

詳細: paginate オブジェクトのプロパティ一覧は、第2章のリファレンスで扱います。

`render`

役割: 部分テンプレートを呼び出し、引数を渡して描画する。
構文:
結果: 指定した部分テンプレートの出力が、呼び出し位置に挿入されます。

{% render "article-card", article: article %}

`collection`

役割: コレクション（サイト機能の部品）を出力する。
構文:
結果: 指定したコレクションが出力されます。

{% collection "vote1" %}

`form`

役割: フォーム（サイト機能の部品）を出力する。
構文:
結果: 指定したフォームが出力されます。

{% form "vote1" %}

注意: form / collection はタグ 1 行で出力されます（endform / endcollection は不要です）。

`cache`

役割: 指定したキーでブロックの描画結果を一定時間キャッシュする。
構文:
結果: ブロック内の出力がキャッシュされ、同条件の表示を高速化します。

{% cache site, "some_key", max_ttl: 600 %}
  {{ site.title }}
{% endcache %}

注意: ログイン状態などで内容が変わるブロックは、キャッシュ範囲に含めないことを推奨します（表示崩れの原因になります）。

`consent`

役割: 同意（同意済みかどうか）に応じてブロックの表示を制御する。
構文:
結果: 指定した同意がある場合に限り、ブロック内が出力されます（運用設定により異なる場合があります）。

{% consent "tracking" %}
{% endconsent %}

`file`

役割: テーマ内のファイルを指定して読み込む。
構文:
結果: 指定したファイルの内容が挿入されます。

{% file "/theme/original/css/theme.css" %}

`javascript_pack_tag`

役割: JavaScript のパックを読み込むタグを出力する。
構文:
結果: JavaScript の読み込み用タグが出力されます（属性は引数に依存します）。

{% javascript_pack_tag "application", async: true %}

`selectfor`

役割: 一覧要素から必要な値だけを取り出し、反復する。
構文:
結果: 括弧内で指定した変数名に値が入って、ブロックが繰り返し出力されます。

{% selectfor (title, path) in site.articles %}
  {{ title }}
{% endselectfor %}

よく使う組み合わせ（短い例）

一覧をページ分割してカードを描画する

{% paginate site.articles per 10 %}
  {% for article in paginate.collection %}
    {% render "article-card", article: article %}
  {% endfor %}
{% endpaginate %}

よくある誤り

複数データを `{{ }}` で丸ごと出さない

複数件の一覧は、for / selectfor / paginate のいずれかで展開します。

{% for article in site.articles %}
  {{ article.title }}
{% endfor %}

参照ガイド

値の加工は、第3章「フィルタ」で扱います。
トップレベル変数の入口は、第3章で扱います。
オブジェクトの詳細（プロパティや関係）は、第2章の各リファレンスで扱います。

トップレベル変数（テンプレートに最初から入るもの）

導入

この章は、テンプレートのどこからでも参照できる「トップレベル変数」の入口です。
変数ごとの詳細（プロパティやリレーションの意味）は、各リファレンスを参照してください。

誰向けか

Clipkit のテンプレートを編集し、表示の差し替えや保守を行う担当者向けです。

扱う範囲

この章は、トップレベル変数の「入口」として、代表的な変数名と最小の例を示します。
各変数の詳細（プロパティ一覧等）は、第2章の各リファレンスを参照してください。

各節の読み方

本章の各変数（小見出し（第3見出し））では、原則として次の順で示します。

役割（何のために参照するか）
例（最小）
注意（失敗しやすい点がある場合のみ）
詳細（必要な場合のみ、参照先を示す）

何がトップレベル？

この章でいうトップレベル変数は、次の二種類です。

ほとんどのテンプレートで参照できる変数（例: request）
画面・テンプレートの文脈に応じて渡される変数（例: site / article）

分類（どこから探すか）

表示用: page_title
システム情報: system
EC: ec_site
アクセス文脈: request
レイアウト差し込み: content
ログイン文脈: current
画面・テンプレート文脈で渡されるもの: site / article / category / tag / user / theme
定数: Constant

よく触るトップレベル（最小セット）

`page_title`

役割: ページのタイトル文字列（表示用）。
例:

{{ page_title }}

`system`

役割: システム情報（名称、バージョン、URL 等）。
例:

{{ system.name }}
{{ system.version }}
{{ system.url }}
{{ system.domain }}
{{ system.root_path }}

`ec_site.root_url`

役割: EC サイトのルート URL。
例:

{{ ec_site.root_url }}

`request`

役割: 現在のアクセス（パス等）の文脈を参照する。
例:

{{ request.path }}

注意: 参照できる項目は、表示している画面の文脈に依存します。
詳細: request の各プロパティは、第2章のリファレンスで扱います。

`content`

役割: レイアウト等から差し込まれる本文領域。
例:

{{ content }}

`current.user` / `current.ec_user`

役割: ログイン中ユーザー（または EC ユーザー）を参照する。
例:

{{ current.user }}
{{ current.ec_user }}

注意: 未ログイン時は空になることがあります。表示の分岐が必要な場合は、条件分岐（if）と併用してください。
詳細: ユーザーの各プロパティは、第2章のリファレンスで扱います。

呼び出し元が渡す変数（例）

テンプレートや画面によって渡される代表例です。

site
article
category
tag
user
theme

詳細は、該当オブジェクトの項目を確認してください。
※ theme は「渡されることがある変数」の例です。参照できるプロパティはテンプレートの利用に合わせてください。

よく使うパターン（短い例）

タイトルを出す

{{ page_title }}

未ログイン時の表示を分ける

{% if current.user %}
  ようこそ、{{ current.user.name }}
{% else %}
  ログイン
{% endif %}

現在のパスを確認する（動作確認用）

{{ request.path }}

定数（Constant）

Constant.to_h(...) の中身（定数群）がトップレベルに載ります。
定数名は環境・設定によるため、ここでは列挙せず、確認方法だけ示します。

{{ Constant.to_h | to_json }}

参照ガイド

リファレンスは、テンプレートから参照するオブジェクトの説明です。Liquid では site のように変数名で参照します。
加工（フィルタ）は、第3章で扱います。
制御/部品（タグ）は、第3章で扱います。

1 件

目次

はじめに

本ドキュメントの位置づけ

本ドキュメントで得られること

対象読者

本ドキュメントの進め方

取り扱わない内容

コード例について

Clipkit Liquid 基本の使い方

基本の使い方

概要

基本構文

データ処理の流れ

単数データと複数データ

単数データ

複数データ

主なデータ

記事一覧の表示

記事詳細の表示

{{ article.title }}

本文の表示

まとめ

基本的な記述パターン

概要

記事一覧の表示

記事一覧（リンク付き）

記事詳細の表示

{{ article.title }}

本文の表示

タグ一覧の表示

カテゴリの表示

著者の表示

コメント一覧の表示

ページネーション

件数制限

並び替え

検索結果の表示

条件による絞り込み

まとめ

リファレンスの読み方

このリファレンスでの用語

既定テンプレートと、デフォルトで渡される変数

既定テンプレート（代表）

どのテンプレートでも参照しやすい変数

まず覚える読み方（最小）

1) 値の出力（{{ }}）

2) 一覧の展開（for / selectfor）

「型」表記について（重要）

オブジェクト（03-）を読む順番（最小）

迷ったときの見方

既定テンプレートとデフォルトオブジェクト

導入

誰向けか

扱う範囲

既定テンプレート

デフォルトオブジェクト（文脈で渡される代表例）

参照先（リファレンス）

制作者が定義する変数と混同しない（命名と退避）

1) 既定名（デフォルトオブジェクト名）を再利用しない

2) 制作者の変数には接頭辞を付ける

3) やむを得ず既定名を上書きする場合は、先に退避する

参照ガイド

site

関連リレーション

構造

型

アクセス

サンプルコード

サイトタイトル

記事一覧（最小）

タグ一覧（最小）

プロパティ一覧

current

cache_key

title

top_title

name

description

url

path

1) 値の出力（`{{ }}`）

2) 一覧の展開（`for` / `selectfor`）

オブジェクト（`03-`）を読む順番（最小）