概要
github pagesを理解するためにまとめたものです。
2024-04-01追記
[email protected]以上になると、bundle exec jekyll serve --watchでやると、次のようなエラーが出るようになったjekyll 4.4.3 | Error: undefined method `[]' for nil /opt/homebrew/opt/ruby/lib/ruby/3.3.0/logger.rb:384:in `level': undefined method `[]' for nil (NoMethodError) ...省略...いろいろ調べたが、Ruby (Versioning) Hell with Jekyll & GitHub Pagesからヒントをもらい、次のように対応した
$ brew install rbenv rbenv ruby-build $ which rbenv /opt/homebrew/bin/rbenv $ rbenv install 3.2.3 $ ruby -v $ ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [arm64-darwin23] $ echo 'eval "$(rbenv init - bash)"' >> ~/.bash_profile $ echo "rbenv global 3.2.3" >> ~/.bash_profile $ echo "rbenv local 3.2.3" >> ~/.bash_profile $ source ~/.bash_profileこれまでやったら、準備ができました。
$ gem install bundler $ bundle -v Bundler version 2.5.7 $ bundle exec jekyll serve --watch ...省略... Server address: http://127.0.0.1:4000/xxxxx/xxxxxx/ Server running... press ctrl-c to stop.が表示されるようになりました！
GitHub Pagesとは
https://docs.github.com/ja/[email protected]/pages/getting-started-with-github-pages/about-github-pages によると
GitHub Pages は、GitHub Enterprise Server のリポジトリから HTML、CSS、および JavaScript ファイル を直接取得し、任意でビルドプロセスを通じてファイルを実行し、ウェブサイトを公開できる静的なサイトホスティングサービス
ということ。
簡単にいうと、github.comにアカウントがある人はどなたでも利用可能で、HTMLやMarkdownなどで記述したコンテンツをWeb上公開させることが仕組みです。
GitHub Pagesサイトには、次の使用制限があります
PHP、Ruby、Pythonなどのサーバーサイド言語をサポートしていない。- ソースリポジトリには、1 GB の推奨上限があります。
- サイトは1GB以上であってはなりません。
Jekyll（ジキル）について
https://docs.github.com/ja/[email protected]/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll によると
Jekyllは、GitHub Pagesに組み込まれている静的サイトジェネレータで、ビルドプロセスを容易化できます。 JekyllはMarkdownおよびHTMLファイルを取り込み、選択したレイアウトに基づいて、完成された静的ウェブサイトを作成します。 Jekyllは、Markdownと、サイトに動的コンテンツを読み込むテンプレート言語のLiquidをサポートします。
Wikipedia によると、JekyllはGitHub.comの創業者や前CEOである Tom Preston-Werner さんが2008年に最初に作られたという。
Jekyllを理解する
Jekyllの本家 Features
- Simple No more databases, comment moderation, or pesky updates to install—just your content.
- Static Markdown, Liquid, HTML & CSS go in. Static sites come out ready for deployment.
- Blog-aware Permalinks, categories, pages, posts, and custom layouts are all first-class citizens here.
Jekyllを使用してGitHub Pagesサイトを作成する
ref: 参考資料 （この方の github.comのリポジトリ）
前提条件
Quickstart のPrerequisitesを満たしているかをまず確認します。
rubyをインストール
rubyはmacOSデフォルトの/usr/bin/rubyであるため、brewを使って最新バージョンをインストールします（参考：Installing Ruby）。
$ brew install ruby
...省略...
インストール直後にterminalに出ていた以下のメッセージ:
==> ruby
By default, binaries installed by gem will be placed into:
/usr/local/lib/ruby/gems/3.1.0/bin
You may want to add this to your PATH.
ruby is keg-only, which means it was not symlinked into /usr/local,
because macOS already provides this software and installing another version in
parallel can cause all kinds of trouble.
If you need to have ruby first in your PATH, run:
echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> /Users/xxxxxxxx/.bash_profile
For compilers to find ruby you may need to set:
export LDFLAGS="-L/usr/local/opt/ruby/lib"
export CPPFLAGS="-I/usr/local/opt/ruby/include"
に従って.bashrcに設定しておきました。
最新のrubyをインストール後の環境。
| Softwares | Version Conditions | My Environment |
|---|---|---|
| Ruby | ≧ 2.5.0 | 3.1.3p185 |
| RubyGems | - | 3.3.26 |
| GCC and Make | - | Apple clang version 14.0.0 GNU Make 3.81 |
bundlerとjekyllをインストール
$ sudo gem install jekyll bundler
...省略...
29 gems installed
上の状態では、bundlerが/usr/local/opt/ruby/bin/にインストールされましたが、jekyllは正しくインストールされませんでした、なぞです。いろいろ調べました所、下記
Troubleshooting の「On macOS, you may need to update RubyGems (using sudo only if necessary):」からヒントを得ることができました。
$ sudo gem update --system
上記コマンドラインの出力結果
その後、次のようにjekyllをインストールすることができました
$ sudo gem install jekyll
Password:
Successfully installed jekyll-4.3.1
Parsing documentation for jekyll-4.3.1
Done installing documentation for jekyll after 0 seconds
1 gem installed
$ which jekyll
/usr/local/opt/ruby/bin/jekyll
$ jekull -v
jekyll 4.3.1
ようやくjekyllコマンドをローカルで実行可能な状態にできました（長かった）。
サイトを作成する
- 公開対象用のプロジェクトを作成してgit初期化する。
$ mkdir pages-test $ cd pages-test $ git init - 公開サイト用のテンプレートを生成する。
$ jekyll new --skip-bundle . New jekyll site installed in /Users/xxxxxxxx/dev/github/pages-test. Bundle install skipped. $ tree . ├── 404.html ├── Gemfile ├── _config.yml ├── _posts │ └── 2022-12-28-welcome-to-jekyll.markdown ├── about.markdown └── index.markdown 1 directory, 6 filesこのコマンドにより、デフォルトのテンプレート用の
markdownファイルやGemfileなどが生成されます。 Gemfileの内容を修正する。- gem “jekyll” の行をコメントアウト。
- # gem “github-pages” で始まる行を編集し、 行を次のように変更します。
gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_pluginsGITHUB-PAGES-VERSION を、サポートされる最新バージョンの
github-pages gemで置き換えますが、Dependency versions をみると、最新が227でありました（2022/12/28時点）
bundle installにより依存ライブラリをダウンロード。$ bundle install- 必要に応じて
jekyllの設定ファイル_config.ymlの内容を修正。$ vim _config.yml url: "" # the base hostname and protocol for your site, e.g. http://example.com baseurl: /pages-test # place folder name if the site is served in a subfolder - 変更内容を
git commitしてリモートリポジトリにpush。$ git branch -m main $ git add . $ git commit -m 'Initial' $ git remote add origin [email protected]:USER/pages-test.git $ git push origin main
Pagesをローカルでテストする
ref: 参考資料
- ローカルでJekyllサイトを実行する
$ bundle add webrick # This may be needed if you use ruby 3 or higher
$ bundle exec jekyll serve
Configuration file: /Users/xxxxxxxx/dev/github/pages-test/docs/_config.yml
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
Source: /Users/xxxxxxxxx/dev/github/pages-test/docs
Destination: /Users/xxxxxxxxx/dev/github/pages-test/docs/_site
Incremental build: disabled. Enable with --incremental
Generating...
Jekyll Feed: Generating feed for posts
done in 0.183 seconds.
Auto-regeneration: enabled for '/Users/xxxxxxxx/dev/github/pages-test/docs'
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
ブラウザからhttp://127.0.0.1:4000/にアクセスすると、
のように表示されました！ （Webサーバを止める時はforegrandで実行中のterminalにてctrl-cで）。
上のページの「Welcome to Jekyll!」リンクをクリックすると、次のような画面が表示されます。
GitHub Pages上公開します
ref: 参考資料
- Deploy from a branch
mainブランチで/root配下を使う
「Save」ボタンを押します。- 設定後、自動で
GitHub Actionsのworkflowが実行されてビルドとデプロイが実行される。
- 公開されたページを確認する。
- デフォルト以外に追加したページの確認。
上記ページにある GitHub Pages Study は
pushする前に新規作成したページ（Postともいう）であり、作成方法とその中身は以下に説明します。_postフォルダに2022-12-29-github-pages.mdファイルを作成し、その先頭の一部を以下に示します。
---
layout: post
title: "GitHub Pages Study"
date: 2022-12-29 18:18:00 +0900
categories: blog
---
# 概要
github pagesを理解するためにまとめたものです。
# GitHub Pagesとは
Postを追加する際の書き方や注意事項などは、この資料 がいい参考になります。
まとめ
Jekyllを使ってGitHub PagesにMarkdown形式のファイルを公開する方法を試しました。純粋なテキストファイルベースで、手軽に利用できることが一番の魅力かなと感じました。当然、Jekyllを使わないで、静的なindex.htmlファイルを作って公開する方法ももちろん可能ですが、これについて今回は割愛します。