第3章セクション13　Liquidの概要

この章では、Jekyllでサイトを作る上で中心となるLiquidを説明しますが、チュートリアルではなく、レファランス的な内容です。必要に応じて適宜参照してください。また、LiquidとJekyllには、わかりやすいドキュメントがありますので、そちらも参考にしてください。

ただし、これらは最新バージョンのドキュメントであり、GitHub Pagesで使われているバージョン（執筆時点では、Liquid 4.0.4, Jekyll 3.10.0）とは異なる部分があります。該当バージョンのドキュメントを手に入れるには、それぞれのGitHubレポジトリからソースコードをダウンロードし、それぞれのバージョンのドキュメントを生成する必要があります。その方法は後ほど説明します。

Liquidの基本

LiquidはHTMLの中に埋め込みます。その埋め込まれたHTMLやMarkdownをテンプレートと呼んでいます。ちょうどphp、あるいはRailsのeRubyに似ています。 Liquidは3つのもの（オブジェクト、タグ、フィルター）を埋め込みます。

オブジェクト

オブジェクトは、何らかの情報を持っているもので、変数によって参照されます。例えば、pageという変数はページの情報を持っているオブジェクトを指しています。その情報はドット記法で参照します。

page.title ページのタイトル
page.description ページのディスクリプション

オブジェクト「page」につけたドットの後の部分をプロパティといいます。 titleやdescriptionはpageオブジェクトのプロパティです。ページのフロントマターに記述されたものはプロパティになり、ドット記法で参照することができます。

オブジェクトをHTMLの中に埋め込んで表示するには二重波カッコを使います。

{{ page.title }}

フィルター

フィルターは縦棒|で左の出力を右に流すものです。ちょうどシェル・スクリプトのパイプのようなものです。出力結果はHTMLに表示することが多いので{{ }}を使うことが多いです。

{{ page.title | escape }}

パイプの右側にフィルターの動作を記述します。 escapeはHTMLで特殊な意味を持つ記号をエスケープします。例えば<を<と変更します。

フィルターには多くの種類があります。また、他の言語における演算子やメソッドの役割をフィルターが担っています。

Jekyllで使う変数

Jekyllで使える変数はJekyllのドキュメントに書かれています。

site: サイト全体に関わる設定やデータを保持。_config.ymlの情報もsiteのプロパティになる
- site.posts: サイト内の全ブログ記事のリスト
- site.pages: サイト内の全固定ページのリスト
- site.categories: ブログ記事の全カテゴリーのデータ。次のセクションで詳しく説明
page: ページ（または記事）固有の情報を保持。フロントマターの情報もpageのプロパティになる
- page.title: タイトル
- page.url: ページのURL（/about/index.html など）
- page.path: ソースファイルの場所
layout: レイアウトファイル（_layouts/ 内のファイル）の中でのみ利用可能
content: レイアウトファイルで使用。そのレイアウトを適用している「ページや記事の中身」が丸ごと代入される
jekyll: Jekyllシステム自身の情報を保持
- jekyll.version: Jekyllのバージョン
- jekyll.environment: ビルド環境（developmentかproductionか）
paginator: パジネーター。ブログ記事がたくさんある場合など、それをページに分割するときに使う

グローバル変数のプロパティの詳細についてはJekyllのドキュメントを参照してください。

Liquidのオペレーター

Liquidのオペレータはコントロールフロー（ifなど）やループ（for）の条件に使えます。

==
!=
>
<
>=
<=
or
and
contains: 左側の文字列が右側の文字列を含んでいればtrue

andとorが複数ある場合は右から順に評価されます。また、かっこ( )で評価順を変更することはできません。

Liquidには二項演算しとしての算術演算子（加減乗除）はなく、フィルター（plus、minis）を使います。

タグ（Liquidの制御構造）

項目が多いので、以下の説明は極めて簡単になっています。詳しい説明はLiquidのドキュメントを参照してください。

コントロール・フロー

コントロール・フローは条件分岐のことです。他の言語と同様の条件分岐ができます。コントロール・フローは次の2種類です。

if/unless （条件）〜 elsif/else 〜 endif
case（条件）when 〜 [when 〜] else 〜 endcase

イテレーション（ループ）

ループをLiquidではイテレーションと呼んでいます。

for （条件）〜 else 〜 endfor: elseは条件が成り立たなかった時に出力される
break: ループを中止して外にでる
continue: ループの現在の回をスキップして次の回にすすむ
forループにはlimit/offset/range/reversedのオプションをつけることができる
forの中でcycle （項目のリスト）を使うことができる。 1回目はcycleの引数リストの最初の項目、2回めは2番めの項目・・・と出力される
tablerow: ループの中で表の行を出力する（tdタグなどが自動的に付く）。 cols/limit/offset/rangeのオプションをつけることができる

tablerowはHTMLの表を作れるので便利です。 HTMLテンプレートであるLiquidらしい機能です。

テンプレート

comment 〜 endcomment: コメントとして扱われHTML出力されない
raw 〜 endraw => Liquidの解釈をせずにそのまま出力される。 {{ }}や{% %}をそのまま出力したい場合に使う

以下は、Liquidのバージョン5以降の機能で、現時点のGitHubではまだサポートされていない。

liquid: 複数行にわたりLiquidの構文を書くことができる。いちいち{% %}で囲まずにすむのがありがたい。（GitHubの2026/2/13時点のLiquidバージョンは4.0.4）
echo: タグの中で用いられ、echoの次の要素を出力する。フィルターに用いる
render: 他のテンプレートファイルを読み込む

変数への代入など

assign: 変数への代入をする
capture: 変数への代入をする。代入するものが長いときに用いられることが多い（下記の例参照）
increment / decrement: 引数に変数をとり、0/-1からはじめて変数を1ずつ増加／減少させ、その値をHTMLに出力する。

assignとcaptureの例

JekyllのLiquidで良く用いられるフィルター

以下では、JekyllのLiquidで良く用いられるフィルターを説明します。いくつかのテーマを調べ、使用頻度の高い順に並べたので、ある程度一般性のある順番になっていると思います。

default

パイプの左側からの入力がnil、false、空文字列のいずれかであるときに引数の値を出力し、それ以外は入力をそのまま出力します。

{{ page.title | default: 無題 }}

ページタイトルが設定されていれば、その文字列を出力
ページタイトルが設定されていなければ「無題」を出力

最も使われているフィルターです。

relative_url

ベースURL（_config.ymlの中で定義）を先頭に付け加えたURLにします。 Liquidでpage.urlを参照するときなどにrelative_urlが必要になります。

_config.yml での定義
baseurl: /my-blog

これにより、出力は次のようになる
{{ "/assets/images/abc.png" | relative_url }}
=> /my-blog/assets/images/abc.png

baseurlのデフォルト値は空文字列です。

absolute_url

文字列の先頭にsite.urlとsite.baseurlを加えます。前提として_config.ymlにurlを登録することが必要です。

url: https://username.github.io

文字列の最後にスラッシュはつけません。デフォルト値はhttps://localhost:4000です。

escape

escapeはHTMLで特別な意味を持つ文字をエスケープします。

< ⇒ <
> ⇒ >
& ⇒ &

これ以外にもエスケープ文字はあるので、詳細はインターネットで調べてみてください。とくに<と>が現れるとHTMLタグと解釈されてしまうので、文字そのものを出力するにはescapeフィルターをかけてやります。

これは、テーマの開発者やサイトの構築者とコンテンツ入力者が別のときにとりわけ重要です。例えばpage.titleにエスケープしなければならない文字が入っているかどうかはコンテンツ入力者しか分かりません。開発者は特別な文字の有無に関わらずきちんとした出力を得るためにescapeを使います。

{{ page.title | escape }}

strip_html

HTMLタグを取り去りたいときに使います。 markdownifyを使う後に使うことが多いと思います。 markdownifyの説明は後でします。

{{ f.image_caption | markdownify | strip_html }}

「マークダウンをHTMLに変換してタグを取る」ということは、ベタなテキストを手に入れることになります。

replace

文字列置換です。 1番めの引数を2番めの引数に置換します。

{{ "暑いなあ" | replace: "暑い", "寒い" }}
=> 寒いなあ

split

文字列を、引数をデリミタとして分割した配列にします。

{% assign ary = "abc, def, ghi, jkl" | split: ", " %}
{% for s in ary %}
  {{ s }}
{% endfor %}
=>
abc
def
ghi
jkl

markdownify

これは、Jekyllが拡張したフィルターです。マークダウンで記述された文字列をHTMLに変換します。マークダウンで書かれたデータを処理するケースで使います。

date

タイムスタンプを別の形式の時刻表示に切り換えます。形式の指定は引数の文字列で与えます。形式にはstrftimeが用いられます。

{{ "2022-8-21" | date: "%Y 年 %m 月 %e 日" }}
=> 2022 年 08 月 21 日

remove

引数の文字列を削除します。

{{ "<p>abcd</p>" | remove: "<p>" | remove "</p>" }}
=> abcd

第3章 セクション13 Liquidの概要