はじめに

先日、個人開発で作った Alexa Skill をリリースしました！

それに伴い、プロジェクトの説明ページを GitHub Pages 使って作ったのですが、
公式のマニュアルや他の記事を見ても分からなかった点をまとめたいと思います。

GitHub Pages とは

Github が提供する静的サイトのホスティング機能です。
無料でサイトを公開できるので、ブログなどのホスティングに利用している人もいるようです。

ただし、無料で公開できるのはパブリックレポジトリのみです。
プライベートレポジトリでGitHub Pages を利用すると、レポジトリの中身が公開されるか、有料プランを契約する必要があります。

GitHub Pages はデフォルトで Jekyll をサポートしています。
Jekyll は Markdown で静的サイトを作成できる Ruby の Static Site Generator です。
Jekyll のコンフィグファイルと Markdown ファイルを配置しておけば、レポジトリに push するだけで、GitHub Actions によってサイトのビルドとデプロイを自動化されます。

Tips

この記事では、GitHub Pages の細かい設定方法などは省き、最初に書いた通り、マニュアルを読んだだけでは分からなかった Tips を記載します。
細かい設定方法や GitHub Pages の立ち上げ方は参考の章に挙げた記事等を参照してください。

GitHub Pages を公開できるレポジトリ

正直、これが一番分かりづらかった点です。
公式ドキュメントだと、GitHub Pages を公開できるレポジトリは <user名>.github.io または <organization名>.github.io となっています。

リポジトリの名前と、任意で説明を入力してください。ユーザーまたは Organization サイトを作成する場合は、リポジトリに .github.io または .github.io という名前を付ける必要があります。

しかし、他の有志の記事では任意のレポジトリでも公開できるとあり、混乱させられました。

正解は、どちらも正しいです。
ただし、任意のレポジトリで公開できるようにするためには、最初に <user名>.github.io または <organization名>.github.io でサイトを公開する必要があるようです。

この理由は GitHub Pages で公開したサイトの URL が https://xxx.github.io/ で始まるドメインになるためだと考えられます。

xxx.github.io レポジトリでサイトを公開すると、その URL は https://xxx.github.io になります。
そして、任意のレポジトリ名で公開する場合、公開されたサイトの URL は https://xxx.github.io/<レポジトリ名>/ となります。
つまりトップページがないと、その下に続く階層のページは作れないということです。
(本当は裏ではサイトができて公開されていたのかもしれませんが、未確認です。)

自分の場合も、最初は任意のレポジトリ名では GitHub Pages の設定ページで Visit site のリンクが出てこなかったのですが、xxx.github.io のレポジトリでサイトを公開した後には表示されるようになりました。

実際に作成した GitHub Pages サイトがこちらになります。
xxx.github.io というレポジトリ名でなくてもサイトを公開することができました。

公開するサイトの階層構造に注意

上記に関連してなのか、Jekyll で作成するサイトの階層構造にも注意が必要です。
当初は <ユーザー名>.github.io レポジトリにて、以下のような階層構造で Web ページを構築することを考えていました。
しかし、GitHub Pages では content1, content2 配下にあるページは表示されません。

.
├── content1
│   ├── index.md
│   ├── sub-content1.md
│   └── sub-content2.md
├── content2
│   ├── index.md
│   ├── sub-content1.md
│   └── sub-content2.md
└── index.md

ローカルで Jykyll を使って動作確認した場合は、上記のようなページ構成でも問題なく表示できます。
しかし、いざ GitHub Pages にデプロイしてみると、content1, content2 のトップページまでは表示できるのですが、
その配下にあるページは 404 になってしまいました。

GitHub Pages で 404 が表示される問題については、生成されている html ファイルが index.html でないと GitHub Pages によって認識されないという意見も散見されます。
実際に、sub-content1.md などを sub-content1/index.md に変えてみましたが、結果は変わりませんでした。

よく見ると 404 になってしまったページは、想定していた URL とは異なっていました。
上記の階層の通り https://xxx.github.io/content1/sub-content1 となってほしかったのですが、実際には https://xxx.github.io/sub-content1 となっていました。

既に記載したように、GitHub Pages では、任意の名前のレポジトリでサイトを公開でき、サイトは https://xxx.github.io/<レポジトリ名> 公開されます。
この仕様のためなのか、Jekyll を使って掘れるページ階層は制限されているのかもしれません。

GitHub Pages でブログを運営している人もいるようなので、ブログの posts ディレクトリ配下のページなどは影響を受けないのでしょう。
試してはいないですが、素の HTML でページを構築してデプロイすれば、自由にページ階層をデザインすることができるのかもしれないです。

Jekyll の Theme の適用の仕方

過去のバージョンでは、Jekyll の Theme の適用を GitHub Pages の設定ページからできたようですが、2023年6月の時点では、そのようなメニューはなくなっていました。
Theme の適用は、各 Theme の Github の説明に倣いました。

Gem の追加方法

よく Gemfile にインストールしたい gem を直接書き込むようなことが書かれている記事を見ますが、これをやると gem 間の依存関係が壊れて Jekyll の起動に失敗しました。
gem を導入や削除は bundle コマンドを使いましょう。

bundle add <Gem name>
bundle remove <Gem name>

まとめ

GitHub Pagesで規模の大きいサイトを作るには

Jekyll のブログ形式にする
複数のレポジトリで GitHub Pages を公開しリンクでつなげる

とする必要があると理解しました。

参考

はじめてのJekyll + GitHub Pages

Jekyll を使用して GitHub Pages サイトを作成する