Jekyll
静的サイトジェネータ Jekyll（ジキル）についてまとめています。
目次
公式・関連サイト
Jekyll - 公式サイト
Jekyll 日本語翻訳ページ
jekyllrb-ja/jekyllrb-ja.github.io | GitHub
公式サイトの翻訳をして公開しているため、公式サイトより情報が古い場合があります。
テーマ
公式サイトそのものではテーマを紹介していませんが、
いくつかテーマを一覧しているサイトが別に存在していて、
公式サイトではこれらをリンクしています。
jekyll new フォルダ で新規サイトを生成した場合、
現在のバージョンではテーマ Minima を適用します。
jekyll/minima | GitHub
🎈 Minima テーマ | remotetheme.github.io - 使用例
🎈 remotetheme/minima | GitHUb - 「Minima テーマ」のソース
GitHub Pages テーマ
GitHub Pages で採用されているテーマも Jekyll でビルドされているため、
これらのテーマも使用する事ができます。
GitHub プロジェクトの Releases で公開したプロジェクトのリンクが付きますので、
_config.yml の次を設定して非表示にすると良いでしょう。
show_downloads: false
github:
is_project_page: false
ファイル構成
Jekyll ではプロジェクト直下が生成されるサイトのルートになり、
.md ファイルが .html ファイルにビルドされ、_site 内に入ります。
index.md があれば _site/index.html で生成されます。
他のファイルは通常変換されず、そのまま _site 内に入ります。
（例外があり、Front Matter を付加したファイルは変換・テーマ適用されます）
GitHub Pages では Not Found は 404.html を参照するため、
その Markdown ファイル 404.md が Not Found に対応します。
頭に _ が付くファイルやフォルダ（ディレクトリ）が
Jekyll 関連特有のファイル・フォルダです。
_config.yml
サイト全体の設定ファイルです。
_include
{% include ファイル.html %} で読み出されるファイルです。
通常 _layouts/ 内のテンプレートファイルから読み出されます。
_layouts
テンプレートファイルです。少なくても default.html は存在します。
Front Matter で layoyut 指定された場合、その .html ファイルがテンプレートになります。
_posts
ブログの記事ファイルはここに入れます。
YYYY-MM-DD-タイトル.html とする決まりがあります。
_site
生成された HTML ファイルなどが入ります。
これをデプロイ・アップロードしてサーバ公開します。
その他
テーマにより _ 頭が付くファイルが生成されている場合があります。
これは公開されません。
ローカルのパソコンなどで動作させる
特に Windows だと Ruby が必須で、
更に Bundler もインストールして使用する事が推奨されています。
Jekyll を使用して GitHub Pages サイトをローカルでテストする | GitHub Docs
Git プロジェクトに設定されている必要があります。 git init で生成します。
Gemfile がない場合は次をテキストに入れで作成します。
source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
シェルを起動します。
Gemfile.lock がない場合は次のコマンドで生成します。
bungle init
Gemfile.lock があれば構成ファイルを最新にします。
bundle update github-pages
bundle 経由で jekyll serve を起動します。
bundle exec jekyll serve
_site 内に HTML ファイルなどがビルドされ、
https://localhost:4000 で参照できます。
Jekyll serve fails on Ruby 3.0 #8523 | GitHub jekyll/jekyll Issues
なお、Ruby 3.0 以降へ更新した後、エラーになる場合は
次のコマンドを実行してみて下さい。
bundle add webrick
_config.yml
テーマにより設定が異なるため、ここではよく使われている主な設定を紹介します。
具体的には適用したテーマに合わせて設定して下さい。
- theme - テーマ。GitHub Pages に備わっているテーマなど gem を参照します。
- remotetheme -
themeの代わりに指定。GitHub プロジェクトから参照します。 - lang - 言語。日本語サイトは
jaです。 - title - サイト名。HTML の
<title>に付与されます。 - tagline - サブサイト名または簡単な説明文。主に表示用です。
- description - サイトの説明。通常 meta タグに使用されます。
- url - URL のうちドメイン名部分までを指定します。
https://example.net.eu.org - baseurl - 通常
/ですが、GitHub プロジェクトページの場合はここに付加し、
https://user.github.io/projectであれば/projectとなります。 - google_analytics: Google Analytics の ID。テーマによって異なる場合があります。
- paginate - ブログの記事一覧で 1 ページに表示する記事数
- plugin - プラグイン。追加する事で機能追加が可能です。
通常テーマがプラグインを適用しているため、実際に追加するプラグインは限定的です。
.md ファイル
頭に Front Matter をつけます。場合により完全省略もできます。
---
layout: default
title: "タイトル"
date: 2021-03-31 21:15:10 +0900
description: "説明"
permalink: /
---
ここから本文です。 **Markdown** を使用します。
- layout - 用途により
defaultpostpaageなど。
テーマによって異なります。テーマの_layoutsを参照して下さい。 - title - タイトル。
<title>内に入ります。 - date - ブログ記事の時につけると日時までの具体的な日付になります。
+0900は日本標準時です。 - description - そのページの説明。
<meta>タグに入ります。 - permalink - そのページのリンク。他のページからのリンクで使われます。
テーマによっては特有の項目が存在します。
GitHub プロジェクトとして公開する
GitHub のプロジェクトとして公開する場合、
次のファイルは必要ではないため、
削除するか gitignore に追加して管理に含まれないようにして下さい。
| ファイル・フォルダ | 解説 |
|---|---|
| Gemfile | 上項目の内容位であれば公開しても構いません |
| Gemfile.lock | 環境によって構成ファイルが変わってきます |
| _site/ 内全て | ビルド済の HTML ファイルなどです |
テーマを改善する
テーマは GitHub プロジェクトに公開されています。
theme では Gem、remotetheme では GitHub プロジェクトを参照しますが、
公開するプロジェクトに同じファイルがある場合は、
公開プロジェクト側で上書きして適用されます。
これを用いて任意のファイルを上書きしてテーマを改善できます。
ヘッダ <head> 関連が多いでしょう。
_includes/head.html などでヘッダ部が存在するか、
_layouts/default.html にヘッダが含まれています。
OGP を追加する
🎈 Open Graph protocol | ふうせん🎈 FU-SEN
テーマで OGP が適用されていない場合、Jekyll SEO Tag で追加するのが便利です。
jekyll/jekyll-seo-tag | GitHub
_config.yml に次を加えます。
plugins がすでに存在している場合はそこに加えて下さい。
plugins:
- jekyll-seo-tag
ヘッダの部分 </head> より前に次を加えます。
{% seo %}
テーマが <title> を適切に出力していている場合は、
Jekyll SEO Tag での出力を無効にできます。
{% seo title=false %}
おそらく OGP を適用するなら、画像も加えたいでしょう。
_config.yml に次の形でデフォルトの画像を入れます。
defaults:
- scope:
path: ""
values:
image: /assets/images/default-image.png
.md ファイルは image で画像を指定する事で、こちらが出力されます。
指定がない場合は _config.yml の画像ファイルが有効です。
---
image: /2021/02/ogp-balloon-domain.jpg
---
独自の CSS を適用する
Jekyll には Sass が備わっているため、
GitHub Pages・Jekyll のドキュメントではどちらも
Sass を使用する前提で説明されています。
テーマの CSS をカスタマイズする | GitHub Docs
Step by Step チュートリアル 7. Assets | Jekyll ドキュメント
ただし、必ずしも Sass を使用する必要はありません。
テーマによって Sass を使用していないため、使えない場合があります。
確実な手段として、</head> の前に追加する .css を追記します。
<link rel="stylesheet" href="/assets/css/styles.css">
これで /assets/css/styles.css に追記していきます。
または <style> で囲って直接スタイルシートを書き込む事もできます。
Web サービスで使用する
次の Web サービスで Jekyll が対応しています。
GitHub Pages
GitHub Pages
🎈 GitHub Pages | ふうせん🎈 FU-SEN
Jekyll は GitHub Pages のバックエンドエンジンとして採用されている事で有名です。
.md ファイルを git push して、HTML に変換表示されます。
Cloudflare Pages
⚡ Cloudflare Pages
🎈 Cloudflare Pages | ふうせん🎈 FU-SEN
2020年12月にベータ版提供が開始された Web サービスです。
Cloudflare アカウントと GitHub を使用します。
Cloudflare のサーバで完全に配信され、サイト数・転送量に制限がないのが大きなメリットです。
（無料アカウントの場合、ビルド月 500 回までなどの制限はあります）
GitHub リポジトリはプライベートでも使用できる、というメリットもあります。
Vercel
▲ Vercel
🎈 Vercel | ふうせん🎈 FU-SEN
ビルド・デプロイ操作に Git の代わりに Vercel CLI が使用できます。
わざわざ Git を使用する事なく、素早くシェルからビルド・デプロイ可能です。
Git リポジトリを使用する場合も GitHub 以外に GitLab・BitBucket に対応します。
ビルド
Jekyll 対応の Web サービス以外で公開する場合は
ビルドを行い、HTML ファイルなどを生成して、デプロイ・アップロードします。
bundle exec jekyll build
デフォルトでは _site/ フォルダ内に生成されますので、このファイルを公開して下さい。
Q&A
エラーが出て動作しません
テーマで使用している文字コードにより発生する事があります。
この場合、ローカルでは動かなくても Web サービスでは正常にビルドされます。
運営者の経験では GitHub Pages のテーマとしても採用されている
Time Machine でも Windows ではエラーになります。
Sitemap は出力しますか？
初期設定では出力しませんが、プラグインが存在します。
_config.yml に次を加えて下さい。
plugins:
- jekyll-sitemap
これで sitemap.xml が生成されます。
ただし Sitemap はプロジェクト毎の生成になるため、robots.txt の記載や
Google Search Console・Bing Webmaster Tools の送信では注意を要します。
Jekyll テーマでブログになっているテーマを通常の Web ページとして使用できますか？
多くのテーマでは、Front Matter で layout: page を指定すると
index.md を含めて通常ページで生成されます。
---
layout: page
title: GitHub Pages
---
テーマによって適用する layout 名が異なりますので、
テーマのプロジェクトページを確認する事をおすすめします。
GitHub Pages でプラグインが動作しません。
GitHub Pages ではセキュリティの考慮上、プラグイン動作が制限されています。
そのため、 _config.yml に加えた plugins で動作しないケースがあります。
予めローカルでビルドしてから GitHub へコミットするか、
他の Web サービスを用いてビルド・デプロイする事を検討しても良いでしょう。
