Jekyll対応Liquid文法チートシート

JekyllのLiquid文法を日本語でまとめたページが見つからない。~~それはね、需要がないからさ~~　ぼちぼちまとめていく。今後も調べたことは追加していく予定である。

## 確認環境

- Windows 10
- Jekyll 4.2.0
- ruby 2.7.2p137 (2020-10-01 revision 5445e04352) [x64-mingw32]
- Bundler version 2.2.2
- Jekyllテーマとして[Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/)を採用

## Jekyllとは

>Jekyllは、個人、プロジェクト、または組織のサイト向けの、シンプルなブログ対応の静的サイトジェネレーターです。 GitHubの共同創設者であるTom Preston-WernerによってRubyで書かれ、オープンソースのMITライセンスで配布されています。

[ウィキペディア（英語)](https://en.wikipedia.org/wiki/Jekyll_(software))

GitHub Pagesと対応させて、ドメイン等にお金をかけずサイトを公開したい人にオススメ。自分も利用し始めている（https://nyshiyama.github.io/mtnishi/）。

### Jekyllを始める場合

かなりざっくりだが、これは本題ではないので...

1. まずは[Jekyll 日本語サイト Step by Step チュートリアル](https://jekyllrb-ja.github.io/docs/step-by-step/01-setup/)を最後までこなす。英語がわかるなら本家サイト[Step by Step Tutorial](https://jekyllrb.com/docs/step-by-step/01-setup/)の方だと最新バージョンに対応している。
   - チュートリアルの最中にRuby用の開発環境も整備が必要
   - Gitは任意となっている（GitHub Pagesを利用する場合は逃げ切れない）

1. 自分で一からサイトを作り上げるもよし、Jekyllテンプレートは無料でも豊富なので、適当にお気に入りを見つけてくるもよし
   - [Jekyll 日本語サイト テーマをピックアップ](http://jekyllrb-ja.github.io/docs/themes/#%E3%83%86%E3%83%BC%E3%83%9E%E3%82%92%E3%83%94%E3%83%83%E3%82%AF%E3%82%A2%E3%83%83%E3%83%97)に複数のJekyllテーマ公開ギャラリーへのリンクがあるのでテンプレを見つけたいならこれらから
   - 詳しい流れは先駆者がまとめてくれている（ex. [ゼロからわかる！GitHub Pagesを使った自前無料ブログの作り方（Jekyll）](https://qiita.com/madoreenu/items/b47833bf785562c77819)）
   - ただし、テーマによっては直接ダウンロード（フォーク）せずともテーマを利用できるものがある（ex. [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/)ではGem-based method、Remote theme method、直接コピーまたはフォーク、の3種類が選択可能）ので、**ギャラリーでお気に入りが見つかったらテーマの使い方をまず確認したほうが良い**

## Liquidとは

>「liquid」とは、Shopifyのサイトを構築する独自のプログラミング言語で、Rubyをベースとして作られています。
Shopifyのサイトは、「HTML」「CSS」「JavaScript」「liquid」で作られているイメージです。
主にHTMLの中でliquidを用いた記述をします。

[【Shopify】独自言語「liquid」の基本的な書き方 - #04 | Web-Guided - web業界で働く方を少しだけ手助けするメディア](https://web-guided.com/1240/#:~:text=%E3%80%8Cliquid%E3%80%8D%E3%81%A8%E3%81%AF%E3%80%81Shopify,%E3%81%84%E3%81%9F%E8%A8%98%E8%BF%B0%E3%82%92%E3%81%97%E3%81%BE%E3%81%99%E3%80%82)

基本も上記リンクで学習できる。その他有用な参考資料として、

- Shopify公式チートシート：[Shopify Cheat Sheet — A resource for building Shopify Themes with Liquid](https://www.shopify.com/partners/shopify-cheat-sheet)
- 配列用のフィルターをまとめたページ：[Array filters](https://shopify.dev/docs/themes/liquid/reference/filters/array-filters#first)
- Jekyllがまとめたページ：[Liquid | Jekyll • シンプルで、ブログのような、静的サイト](http://jekyllrb-ja.github.io/docs/liquid/)

## チートシート

JekyllとLiquidは基本を理解していることが前提である。基本的な設定（YAMLファイル）を整えたら後はポスト（=投稿記事）をマークダウン（.md or .markdown）ファイルで`_posts`フォルダーに保存していくが、Jekyll中のファイルを記述するときにJekyll特有（Liquid特有？ごっちゃにしているかも）の記法が必要となる。

一応、大雑把なフォルダーツリーを載せておく。

```shell
./
├─assets
│  ├─css
│  ├─images
│  └─js
├─_data
├─_drafts
├─_includes
├─_layouts
├─_pages
├─_portfolio
├─_posts
├─_sass
└─_site
```

### コメントアウト

```md
{% comment %}hogehoge{% endcomment %}
```

HTMLの標準的なコメントアウト`<!-- hogehoge -->`は機能しない。しかし、以下のように書いたほうがハイライトしてくれるのでコメントだと分かりやすいかも。

```md
{% comment %}<!-- hogehoge -->{% endcomment %}
```

また、コメントアウト部分だけで文法を成立させておく必要がある。

```html
{% comment %}
    {% if hoge %}
        hogehoge
    {% elsif hogege %}
{% endcomment %}
        hogehogege <-ここだけ有効になってほしいがエラーとなる
{% comment %}
    {% endif %}
{% endcomment %}
```

### テキストをそのまま出力

```md
{% raw %}hogehoge{% endraw %}
```

たとえば、Jekyllポスト上で`{{ page.title }}`をこのまま表示したい場合に利用する。`` `{{ page.title }}` ``と記述しても記事タイトルに変換される。

### ポストへのリンクを出力

**注意！**「[Jekyll v4.0 以降、linkやpost_urlタグの前にsite.baseurlを使用する必要がなくな](http://jekyllrb-ja.github.io/docs/liquid/tags/#%E3%83%AA%E3%83%B3%E3%82%AF)」ったが、GitHub Pages上でビルドする場合、2021/02/06時点でJekyllのバージョンは**3.9.0**（[Dependency versions | GitHub Pages](https://pages.github.com/versions/)）なので、以下の`{% link`または`{% post_url`の手前に`{{ site.baseurl }}`を記述しなければならない。

```md
{% link _posts/hogehoge.md %}
```

記事を作成している段階では`_posts/hogehoge.md`にポストが存在するが、実際に記事として表示されるhtmlファイルは`_site`フォルダーのどこかに存在する（設定依存）ため、mdファイルまでのパスを記述するだけで済むほうが楽。

次のようにポストファイル名（拡張子なし）を指定しても可能。

```md
{% post_url hogehoge %}
```

#### 記事タイトルや日付をリンクタイトルにしたい場合

たとえば以下の`post-file-name-without-the-extension`に記事ファイル名（拡張子なし）を入れると、`[記事タイトル（January 1, 2021）](記事URL）`のように出力される。リンク前後で改行されたくない場合は1行で記述する。

```html
{% capture target_url %}{% post_url post-file-name-without-the-extension %}{% endcapture %}
{% for post in site.posts %}{% assign candidate_url = post.url | relative_url %}{% if candidate_url == target_url %}
[{{ post.title }}（{{ post.date | date: "%B %-d, %Y" }}）]({{ target_url }}){% break %}{% endif %}{% endfor %}
```

### 画像サイズを変更

kramdownマークダウンスタイルの場合。他のスタイルでも可能かどうかは検証していない。

```md
![alt](hogehoge.png){:height="36px" width="36px"}
```

[kramdown公式ページ](https://kramdown.gettalong.org/syntax.html#images)

### 画像までの相対パス

```md
![alt]({{ "/assets/images/hogehoge.png" | relative_url }})
```

`{{ site.url }}`とかを記述してもいいが、`relative_url`のほうがスマート。

### 画像にクラスを定義

```md
![alt](hogehoge.png){: class-name}
```

あとはcssファイルで如何様にも料理できる。

### 画像を左に寄せる（右、中央も同様）

```md
![alt](hogehoge.png){: align-left}
```

で、cssファイルに`align-left`クラスの`float: left`を記述する。

### 数式を挿入

Jekyllプラグインの[spaceship](https://github.com/jeffreytse/jekyll-spaceship#requirements)を利用する。詳細な使い方はリンク先のREADMEを参照する。設定が済めば後は下記のようにTeXスタイルで記述が可能になる。

```md
$ 2^{\frac{n-1}{3}} $
```

spaceshipプラグインは他にも色々とできるようになるらしい。

数式のみでよいなら、MathJaxのみ設定を追加する（[Jekyll 上での数式の表示](https://sekika.github.io/2015/10/10/equation-on-jekyll/)）という手もある。また、KaTeXなら描画速度がより高速らしいが、GitHub Pagesでは利用が面倒くさそう（[JekyllでMathJaxからKaTeXに移行した](https://tex2e.github.io/blog/misc/mathjax-to-katex)）。

### 縦棒（`|`）を本文中に記述

vertical bar（pipe char）とも。そのままだと、リンクのURL等に含まれていてもLiquidの文法の一部として判定されてしまうため表記が壊れる。エスケープしたら記述可能。

```md
\|
```

### エンコード、デコード

デコードの例：

```md
{{ "%27Stop%21%27+said+Fred" | url_decode }}
```

結果は、

```html
'Stop!' said Fred
```

[url_decode – Liquid template language](https://shopify.github.io/liquid/filters/url_decode/)

Liquidとして提供されているので、当然だがポスト以外でも利用できる（各種設定用としてのHTMLファイル上とか）。

### コードのシンタックスハイライト

```md
    ```javascript
    // ここにコードを記述
    ```

    {% highlight javascript %}
    // ここにコードを記述
    {% endhighlight %}
```

どちらでも可能。（インデントはQiitaのコードブロック内でバッククオーテーションを表示させるため：[Markdown コードブロック中にバッククオート3つを表示したい - Qiita](https://qiita.com/usagizmo/items/0c8c6bb54d13e818f2d0)。）

なお、Liquid記法（`{% ... %}`）が含まれた文字列をハイライトする場合は、[`raw`](#テキストをそのまま出力)と併用する。

```html
    <!-- それぞれ行の上下関係に注意 -->

    {% raw %}
    ```html
    <!-- ここにコード -->
    ```
    {% endraw %}

    {% highlight html %}
    {% raw %}
    <!-- ここにコード -->
    {% endraw %}
    {% endhighlight %}    
```

### 変数定義

基本情報は[Variable – Liquid template language](https://shopify.github.io/liquid/tags/variable/)で確認可能。

`capture`は`for`と組み合わせて配列を定義できるなど便利だが、使用するときは改行を入れないように注意する。以下は`capture`で配列`array`を定義し直しているだけだが、改行、インデントで読みやすくした`capture`の定義では同じ結果にならない。

```html
{% assign array = "a,b,c" | split: "," %}
{{ array }} <!-- abc -->

<!-- 改行、インデントなし定義 -->
{% capture capture_sample %}{% for item in array %}{{ item }}{% unless forloop.last %},{% endunless %}{% endfor %}{% endcapture %}
{{ capture_sample | split: "," }} <!-- abc -->

<!-- 改行、インデントで読みやすくした定義 -->
{% capture capture_sample %}
    {% for item in array %}
        {{ item }}
        {% unless forloop.last %}
          ,
        {% endunless %}
    {% endfor %}
{% endcapture %}
{{ capture_sample | split: "," }} <!-- abcではない（以下のようになる） -->
```

上記結果の例：

```html
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>    a
    
      
    

    b
    
      
    

    c
</code></pre></div></div>
```

### アフィリエイトリンクの挿入

場合によってはポストに直ペーストしても表示されないことがある。たとえば「もしもアフィリエイト」で簡単リンク、カード式、ボタンありの場合（[【超簡単】初心者でもできる『かんたんリンク』の使い方【もしもアフィリエイト/WordPressブログ】 | yujiblog.](https://yujiblog.org/how-to-use-kantan-link)）、`<!-- START MoshimoAffiliateEasyLink -->`から始まるHTMLタグをそのままペーストするのではなく、`script`タグの中身（`(function...`）を`/assets/js/affiliate/product-name.js`として保存し、本文中では以下のように`src`で参照する。

```html
<!-- START MoshimoAffiliateEasyLink -->
<script type="text/javascript" src="{{ '/assets/js/affiliate/product-name.js' | relative_url }}"></script>
<div id="hogehoge">リンク</div>
<!-- MoshimoAffiliateEasyLink END -->
```

[html - How to add script tag in jekyll? - Stack Overflow](https://stackoverflow.com/questions/47108702/how-to-add-script-tag-in-jekyll)

## 蛇足

- WindowsでJekyllを利用するなら、コマンドプロンプトより断然PowerShellの方が良い
- `バッチ ジョブを終了しますか (Y/N)?`でY/Nどちらを入力してもCtrl+Cをしても、もう一度同じメッセージが現れて、Y/N/Ctrl+Cどれでも入力したら終了する、たとえNでも...