GitHub PagesでSphinxにCSSが適用されない!!
GitHub PagesでCSSなどのResourceファイルが適用できなくて苦戦したので、メモを残します。
GitHub PagesでCSSなどのResourceファイルが適用できなかった原因として、大きく以下の二つありました。
CSSのファイルパスがサーバとローカルで異なる
- 原因
GitHub Pagesにアップロードした時点で、サーバーとローカルではcssへのファイルパスを変更する必要があります。
例えば、ローカル上のindex.htmlで以下のようにcssのファイルパスを指定し、ブラウザで開くと、一見、index.htmlに_static/asabaster.cssが適用されているように見えます。
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
しかし、これをこのままGithub Pagesにアップロードすると適用されません。
Githube Pages上では、ファイルパスがローカルとは異なるるため以下のように指定する必要があります。
<link rel="stylesheet" href="https://username.github.io/project_name/_static/alabaster.css" type="text/css" />
全てのファイルでパスを変換するのは、結構骨が折れます。
正規表現で一括置換する手もありますが、あまり筋が良いとは言えません。
- 解決策
index.htmlのheaderの先頭に以下のbaseタグを追加してください。
<head>
<base href="{{site.github.url}}" charset="utf-8"/>
...
</head>
baseでsite.github.urlと指定しておくことで、他のファイルパスの基本として、https://username.github.io/project_name/をファイルパス内に展開してくれます。
_staticフォルダをGitHub Pagesが解釈してくれない
- 原因
GitHi Pagesは、デフォルトでJekyIIでホスティングを行います。しかし、このJekyIIは、Sphinxに対応していないため、_staticなどにあるパスを正確に読み取ってくれません。
- 解決策
GithHubPagesを公開しているフォルダ直下に、.nojekyIIという空ファイルを置いて、pushしてください。
.nojekyIIファイルは、「これはjekyIIファイルじゃないよ!」と宣言するためのファイルです。