静的サイトジェネータ Jekyll(ジキル)についてまとめています。


目次


公式・関連サイト

 Jekyll - 公式サイト

 Jekyll 日本語翻訳ページ
 jekyllrb-ja/jekyllrb-ja.github.io | GitHub
公式サイトの翻訳をして公開しているため、公式サイトより情報が古い場合があります。


テーマ

公式サイトそのものではテーマを紹介していませんが、
いくつかテーマを一覧しているサイトが別に存在していて、
公式サイトではこれらをリンクしています。

 Resources | Jekyll

jekyll new フォルダ で新規サイトを生成した場合、
現在のバージョンではテーマ Minima を適用します。

 jekyll/minima | GitHub
🎈 Minima テーマ | remotetheme.github.io - 使用例
🎈 remotetheme/minima | GitHUb - 「Minima テーマ」のソース

GitHub Pages テーマ

GitHub Pages で採用されているテーマも Jekyll でビルドされているため、
これらのテーマも使用する事ができます。

 pages-themes | GitHun

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 - 用途により default post paage など。
    テーマによって異なります。テーマの _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 サービスを用いてビルド・デプロイする事を検討しても良いでしょう。