GitHub Pagesでjekyllを使う時のためのチートシート、Tips・技術情報
アジェンダ
GitHub Pages を作成するにあたって、利用した技術情報などを後で忘れても検索で気付くようにまとめておきます。 自分でも後で「どこにやったかな？」とならないようにチートシートにしました。
チートシート
ここでは Markdown ではなく、jekyll の機能に限定しています。が、ページは Markdown で作成しているので、本ページの解説はほとんどすべてが Markdown です。 純粋な Markdown の解説はこちらに移しました。 ソース部分のカッコは半角です。 GitHub リポジトリも参照してもらいつつ、見比べてもらったほうが良いかも知れません。
GitHub アカウント
表示例：shimajima-eiji
｛｛ site.social-github ｝｝
リンク記法
使用例：site.baseurl と post_url を組み合わせる
｛｛site.baseurl｝｝｛% post_url archive/2019-01-01-operation-rule %｝
/resume/archive/operation-rule
# 参考：siteとpageのurlの違い
｛｛site.url｝｝
https://shimajima-eiji.github.io
｛｛page.url｝｝
/archive/howto-jekyll
# 参考：siteのurlとbaseurlの違い
｛｛site.baseurl｝｝
/resume
｛｛site.url｝｝
https://shimajima-eiji.github.io
この辺りはややこしいので、自サイトでも検証して理解したほうが良いでしょう。
実ファイルパス変数
表示例：_posts/archive/2019-01-01-howto-jekyll.md
｛｛page.path｝｝
たとえば、https://github.com/shimajima-eiji/resume/blob/master/_posts/archive/2019-01-01-howto-jekyll.mdのように指定する方法が考えられます。 が、用法として特殊なのでどうやって使うかは未知数です。コードなら大喜びですが…。
自由変数や_config.yml の値を使いたい
表示例：blob/master
｛｛site.data.github.file｝｝
# _data/github.ymlのfileを取得
ファイルは、https://github.com/shimajima-eiji/resume/blob/master_data/github.ymlの通り。
# アカウント名(site.social-github)を変えたら変更すること
# github pagesについては、siteを使うことで対応可
baseurl: https://github.com/shimajima-eiji
url: https://github.com/shimajima-eiji/resume
file: blob/master
dir: tree/master
執筆時点のものなので変更されている可能性があります。 この方法で_config.yml を使うこともできます。その場合は site 以下を参照すればよいです。
TeX
やはり数式をきれいに書きたいですよね。
見積もりの人月神話で使っているので、こちらを参考にしてみてください。
TOC:目次
markdown ではなく jekyll です。 厳密には jekyll-doc という gem を使っています。 ソースコード
Gemfile に追記する必要はなく、githubpage に内包されています。
環境構築
GitHub Pages で公開することを前提にすると、ちょっとカスタマイズするだけでも気を遣います。 gem githubpages に入ってないものは使えないというつもりで、試行錯誤するブランチを作っておいたほうが良いかも知れません。
開発環境
ローカル環境で確認したい場合、rbenv を使うことになります。 構築手順の通りにやれば OS 不問（Windows や Mac、Linux など）でできると思いますが検証はしていません。
また、今回採用したテーマをベースに拡張しています。 実行する際は、
bundle exec jekyll s --baseurl=""
で実行します。
検証用のプレビューをする方法
たとえば、githubpages.io というリポジトリを公開しているとします。 ここにブランチを切っても見れないので、一時的に確認用リポジトリを作ってそちらにアップロードし、対象のパスで検証します。 チェックが終わったら公開用リポジトリにプッシュするのが良いでしょうか。
GitHub Pages でホスティングできるようにする。
Ruby を入れたのは、jekyll を使えるようにするためです。 Ruby のフレームワークは色々触ってきたけど、静的サイトジェネレーターはあまり意識して使ったことがない1ので、これを機会に使っちゃおうという試みです。
ついでに、Ruby のフレームワークについて、もうひとつ詳しくなれました。
メモ
- 【必須】記事を追加するだけなら GitHub の Web フォーム上でも可能です。
- 【注意】Markdown 記法の種類はKramdown
- 目次は Kradown ではなくjekyll-tocを採用
- 各記事ページよりアポイントができます。