jekyllの使い方とトラブルシューティング

概要

• jekyllはジキルと発音する
• github pagesでサイトを作成できるRuby製のプログラム
• 注意点
  • rubyの2.x系までのサポートなので、rbenvなどでruby 2系の環境で行う必要がある

新規にページを作成する

• root directoryに<url-name>/index.mdを追加
• index.mdには実態を記述したlayoutを記す
• layoutで指定した名前のマークダウンを_layouts/<specified_name>.mdに記す
• <specified_name>.mdにはどのファイルをロードして描画するかのスクリプトを組み込む

localでjekyllをserveする

• ローカルでserveできればgithub.ioでも問題なく動作すると期待できる

bundleで必要なファイルをインストール

$ bundle install

ローカルでサーブする

$ bundle exec jekyll serve

• --incrementalをつけると起動が早いがすべてのドキュメントをコンパイルしないらしく、事前にページのエラーを検出できない

期待したアウトプットになっているかチェック

• ローカルホストでテストサーブした内容をtidyで整形して、batで色をつけて確認できる

$ curl "http://localhost:4000/<target-page>" | tidy | bat

CSSを編集する

• assets/css/main.scssを編集することでデザインを微調整できる
• デフォルトではテーブルの枠が表示されないので表示されるように拡張するなどが可能

template描画エンジンliquid

• 注意
  • liquidはマークダウン中もパースを行おうとするので、{と%の間にスペースを挟んでパースしないようしている

変数の作成

{ % assign varname = "" % }

for loop

{ % for var in array-var % }
  <!-- なにか -->
{ % endfor % }

if

{ % if var == "cond" % }
  <!-- なにか -->
{ % endif % }

arrayのソート

昇順にソート

{ % array | sort: "sort_key" % }

降順にソート

{ % array | sort: "sort_key" | reverse % }

liquidの制約

• site.posts変数があり、ここにマークダウンのデータが格納されているが、このデータオブジェクトは編集が不能であり、値をあとから書き換えたり、特殊なプロパティを追加したりすることができない
  • ソートのためのキーを動的に作成しようと試みたが通常のプログラミング的な発想では難しそうであった

トラブルシューティング

github.io上でアップロードしたはずのファイルにURLでアクセスできない

• 最初の数行にyaml形式のメタ情報を記述する欄があり、そのパースに失敗している可能性
  • "何か"が""何かなどになっていたりパースできない状態などがよくありえる
• ローカルでbundle exec jekyll serveすることでパースに失敗したファイルのエラーが標準出力にでるので確認できる

githubでビルドが失敗する

• ローカルで動作するか確認する
  • 動作しなければ何か問題が発生している

libffi.so.7がない

• askubuntu

Latexの数式のパースに失敗する

• s^2をカッコで囲ったような表現をjekyllはパースに失敗する事がある
• 表現が限定されてしまうがカッコを消す等で対処する

参考

• Quickstart for GitHub Pages