Jekyll を使って GitHub Pages にポストするようになって気づいたことのまとめ。

はじめに

Jekyll で GitHub Pages に載せる文書を書くようになったのだけれど、 書き方 (文法) についてはまだまだわからないことが多く、 ネットで調べながら書いている。

でも、ネットで見つかった事例が手元では動作しないことも多い。

これはバージョンの新旧や、マークダウンを処理するエンジンの違いなどが 影響しているらしい。

なので、これまでにちょっとハマった TIPS をここに記していく。

環境について

Windows PC の Jekyll でプレビューして Git で GitHub に上げる使い方を想定している。

マークダウンのエンジンは Kramdown で、コードハイライトは Rouge だ (2016/02/01 に GitHub Pages で使用する Jekyll が 3.0 になったのにともなって Pygments から Rouge に変更された)。

TIPS

コメントアウト

{% comment %}{% endcomment %} で囲まれた部分がコメントアウトされる。 HTML に出力されない。

{% comment %}
囲まれた部分がコメントとして無視される
{% commentout %}

Liquid のエスケープ

参考: stackoverflow: How to escape liquid template tags?

{% raw %}{% endraw %} で囲む。 または {{ "何か" }} で Liquid として解釈されないように分割する。

例1:

{% raw %}{% something %}{% endraw %}

例2:

{{ "{% something " }}%}

2番目の例では {% something %}"{% somthing ""%}" に分割し、 前半を {{ "何か" }} の中に入れている。

コードブロックのハイライト

{% highlight <lang> [linenos] %}{% endhighlight %} で囲む。 <lang> はコードブロックの言語で必須、 [linenos] は行番号を付けるかどうかのオプション。

~~~ で囲む指定方法もある。

_config.yml に以下の指定をするとコードブロックの区切りに ``` が使えるようになる、との記述を見たが、 試した限りでは動かなかった。

kramdown:
  input: GFM

バッククォートが含まれるインラインコード

参考: Qiita: Markdown でバッククオートを含むインラインコードを書くには

中に現れるバッククォートよりも多く連続するバッククォートで囲む。

PHP のシンタックスハイライト

先頭行が <?php で始まっている必要がある。

シンタックスハイライトのエンジンが pygments だと、 startinline オプションを指定して <?php で開始しないコードブロックを PHP として処理させることが できたようだが、rouge だと動作しない。

{% highlight php startinline %}
echo $_SERVER['HTTP_USER_AGENT'];
{% endhighlight %}

時刻

記事のタイムゾーンは OS のタイムゾーン、 例えば環境変数 TZ が指定されているものが使用される。

Jekyll のドキュメントでは _config.yml で timezone: を指定すると OS のタイムゾーンの代わりに _config.yml で記述したものが使用されるとあったが、 手元ではそうならなかった。

timezone: を指定すると内容にかかわらず UTF になってしまう。

以下は TZ=Asia/Tokyo の状態で date: 2016-02-04 09:03:00 +0900 を date_to_xmlschema で出力した結果。

_config.yml で何も指定しない場合。

2016-02-04T09:03:00+09:00

_config.yml で timezone: Asia/Tokyo を指定した場合。

2016-02-04T00:03:00+00:00