nikkie-ftnextの日記

イベントレポートや読書メモを発信

SphinxでビルドしたHTMLをGitHub Pagesで公開するときの頼れる味方、sphinx.ext.githubpagesを知っていますか？

Sphinx

はじめに

「みんな、ウタだよ！」、nikkieです。

今回はSphinxでビルドしたHTMLをGitHub Pagesで公開するときのtipsをアウトプットします。
sphinx.ext.githubpagesってご存知でしたか？

目次

SphinxとGitHub Pagesを一緒に使うときの落とし穴

reStructuredText（reST）やMarkdownで原稿を書き、ドキュメンテーションツールSphinxでHTMLをビルド、そして、そのHTMLはGitHub Pagesで公開できます！
私が初めて試したとき、1つ落とし穴にハマりました。
それは、「CSSが当たらない」「画像が見つからない」です。

Sphinxをデフォルト設定で使っていたので、ローカル環境ではbuild/htmlディレクトリ1の中の_static/cssにCSSが、_imagesに画像が置かれました。
ところが、ビルドされたファイル（＝build/htmlの中身）一式をGitHub Pagesとして公開すると、CSSや画像にアクセスできません。
アンダースコアで始まるファイルやディレクトリにアクセスできないのです。

これはbuild/html直下に.nojekyllという空ファイルも合わせて置くことで解決します。
ではなぜこの方法で解決するのか、秘密を明かしてみましょう。

GitHub PagesとJekyll

https://docs.github.com/ja/pages/getting-started-with-github-pages/about-github-pages#static-site-generators

GitHub Pagesのドキュメントの「Static site generators」を参照します。

If you publish your site from a source branch, GitHub Pages will use Jekyll to build your site by default.
If you want to use a static site generator other than Jekyll, we recommend that you write a GitHub Actions to build and publish your site instead.
Otherwise, disable the Jekyll build process by creating an empty file called .nojekyll in the root of your publishing source, then follow your static site generator's instructions to build your site locally.

今回の説明に関係するところに絞って訳します（意訳気味です）。

  • GitHub PagesはサイトをビルドするのにデフォルトでJekyllを使う（ref: 1文目後半）
  • 公開しているソースのルートに.nojekyllと呼ばれる空のファイルを作ることで、Jekyllのビルドプロセスを無効にしてください。それから、あなたが使う静的サイトジェネレータがローカルでサイトをビルドするための説明書に従ってください（ref: 3文目）

.nojekyllはJekyllによるサイトのビルドを無効にしているんですね！

また、こんな情報も見つかりました。

This should only be necessary if your site uses files or directories that start with underscores since Jekyll considers these to be special resources and does not copy them to the final site.

訳します：

あなたのサイトがアンダースコアで始まるファイルやディレクトリを使う場合のみ、これ（空ファイル.nojekyllの作成）は必要となるはずです。
なぜならJekyllはそれら（アンダースコアで始まるファイルやディレクトリ）を特別なリソースとみなし、最終的なサイトにコピーしないからです。

アンダースコアで始まるディレクトリ（先の_staticや_images）はデフォルトのJekyllによって最終的なサイトに入ってこないのですね。
だから.nojekyllの配置が必要なんですね！

「要は毎回.nojekyllを作ればいいだけでしょ」と思ったそこのあなた、実はSphinxは.nojekyll作成をサポートしているんです！（バッテリーインクルード！）

Sphinxにおける対処法 sphinx.ext.githubpages

この拡張はGitHub Pagesで公開するために、 .nojekyll ファイルをHTMLディレクトリ内に作成します。

sphinx.ext.githubpagesはSphinxをインストールしてさえいれば使えます。
使い方は、conf.pyのextensionsに書くだけです。

extensions = [
    "sphinx.ext.githubpages",
]

これだけでビルドされたHTMLファイル群に.nojekyllが含まれます🙌
簡単でしょ？

CNAMEの対応もsphinx.ext.githubpagesでできるんです！

GitHub Pagesはカスタムドメインで運用できます。
操作については以下のドキュメントが詳しいです（Configuring a subdomain）。

https://docs.github.com/ja/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain

このGUI操作により、CNAMEというファイルがコミットされます2。

カスタムドメインのCNAMEファイルもsphinx.ext.githubpagesでいい感じに扱えます！（上で紹介したsphinx.ext.githubpagesのドキュメントより）

また、 html_baseurl セットの場合、カスタムドメイン用の CNAME ファイルを作成します。

html_baseurlはconf.pyに設定できます3。

これを使った例が、Python Boot Campのページです。

Python Boot Campのページの例では、pushをトリガーにHTMLをビルドし、自作アクション4によりGitHub Pagesのブランチにforce pushしています。
GUIで作ったCNAMEはforce pushで消えることが懸念されましたが、sphinx.ext.githubpagesが毎回（.nojekyllだけでなく）CNAMEも作ってくれるので、懸念は解消しました。
具体的な設定が知りたい方はソースリポジトリをどうぞ！

終わりに

SphinxでビルドしたHTMLをGitHub Pagesで公開するときに、CSSが当たらない・画像が見つからない事象を解決できるsphinx.ext.githubpagesを紹介しました。
GitHub PagesデフォルトのJekyllを無効化し、アンダースコアで始まるファイルやディレクトリもGitHub Pagesのサイトに含まれるようにしています。

touch .nojekyllする方法は頻繁に見つかるのですが、実はSphinxはデフォルトの拡張機能としてサポートしているんです！
この解決方法は私にはエレガントに見えており、存在を知ってから愛用しています（Sphinxというツールを使いこなしてる気がしますよね、アガル！）。
おんなじように「いいな🤗」と思った方は、ぜひお手元のSphinxプロジェクトで試してみてください！

  1. conf.pyの設定によっては_build/htmlかもしれませんね。その場合は読み替えてください↩
  2. 「this will create a commit that adds a CNAME file to the root of your source branch.」↩
  3. https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-html_baseurl↩
  4. sphinx-revealjsで作ったスライドをGitHub Pagesで公開する - nikkie-ftnextの日記で紹介したftnext/action-push-ghpagesです。 ↩