GitHub Pagesでこのページを公開するにあたってJekyllを採用したものの，あまりに「暗黙の了解」が多すぎるのでわからなかったことを中心にまとめた． この記事を書いたときは少なくともすでにあるthemeを採用しているが，いずれは趣味でフロントも実装したいと感じたため，Sass, Compass, Haml, Vueを使える環境にする．

基本は以下の公式サイトが参考になる:
Jekyll | Transform your plain text into static websites and blogs
このページ自体もJekyllで作られている．
他にも様々なGithub PagesがJekyllで作られているので，参考になる．

設定ファイル: _config.yml
テンプレートエンジン: Liquid template language

Front Matter

以下のようにファイルの先頭をtriple-dashed lines で囲み，YAMLスタイルでページの設定ができるJekyllの機能．

  • layout: _layouts のファイルもしくは既存のテーマ名
  • title
  • permalink: ルーティングを直接指定 e.g.) pages/ → /pages/index.htmlになる
  • published: falseにすると公開されなくなる
  • その他: page.variable でvariableに指定した値を読み出せる 
    ---
layout: post
title: Blogging Like a Hacker
---

ディレクトリ構造

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts `jekyll build/serve --drafts` でみれる
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes ... インクルードするhtml,css,sass,jsファイル
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts ... 記事の投稿用mdファイル
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass Sassファイルのデフォルトパス．`.css` にコンパイルされる
|   ├── _base.scss
|   └── _layout.scss
├── _site
│   └── 生成された静的ファイル．ここを公開すれば良い
└── _plugins
|   └── build時に自動実行されるカスタムプラグイン
├── assets
│   └── ここの名前は何でも良いが，css, jsファイル置き場
├── .jekyll-metadata
└── index.[md,html]  ホーム

Sass

_sass にあるものは基本インポート用で _site に表れない． _sass 以下のファイルをhtmlからインポートしたいscssファイル (assets/css/main.scss とか) から @import できる． コンパイルしてほしいファイルはFront Matterに従いダッシュをつけないと cssにコンパイルされない．

compassをつかう

jekyll-compass もあるがもうメンテされてない．記事は古いが以下に従うといけた．

Jekyll Integration · Compass/compass Wiki · GitHub

_sass/config.rb では相対パスなら前に ../ をつけることを忘れない．

jekyll-haml

haml をhtmlに変換してくれる．

デフォルトでは .md, .html のみのサポートだが .haml もサポートするように．

includeするだけでなく固定ページなど， _site に出力してほしいならFront Matterに従いダッシュをつける．

_includes 中のhamlファイルは必要なく， {% haml xxx.haml %} で読み込める．

Vue.js / Vuetify.js

_includes の中などで，共通部分のヘッダーにCDNのリンクをはって読み込ませておけば良い． このページをスクロールしたときに右下に出るトップに戻るボタンはVueが使われている． material designを使いたかったのとフロント側の実装を楽にしたかったため，Vuetify.jsも利用している．

Configurations

GitHub Pagesで公開する際は，暗黙にデフォルトで設定されている項目がある． Override可なものと不可なものがあるので把握しておく．

Configuring Jekyll

その他参考になるサイト

Using Jekyll as a static site generator with GitHub Pages - User Documentation