Github Pages

Githubでは<username>.github.ioで個人ブログを持つことが出来る。 静的なものしか出来ないが、別途サーバーを用意する必要がない。

<username>.github.ioという名称のリポジトリをつくり、htmlを並べればWebサイトになる。 あるいは静的サイトジェネレータとしてJekyllがサポートされているので、これを用いたWebサイト作りも出来る。

これはHugoを用いてWeb サイトを作ったメモである。 参考としてHugo DocumentationとHugoで新規のWebサイトを作成する、Hugoで1からテーマを作ってGitHub Pagesにデプロイするなどを見た。

Hugoのインストール

Ubuntu20.04ではaptで導入が可能になっている。 公式ではwgetによる導入が記載されていたが、簡単にaptで導入した。

$ sudo apt install hugo

リポジトリ作成（ローカル）

まずはローカルな環境で<username>.github.ioの名前でディレクトリを作ることになるが、mkdirをする必要はなく

$ hugo new site <username>.github.io

を実行することでディレクトリと基本的なツリー構造

<username>.github.io/
├─ archetypes
├─ content
├─ data
├─ layouts
├─ resources
├─ static
├─ themes
└─ config.toml

が出来上がる。 config.tomlが基本となる設定ファイルである。 archetypes/に記事を作る際のテンプレート用ファイルがあり、記事はcontent/に保存していく。 記事は基本的にマークダウンファイル.mdとして作る。

Theme

themes/にWebサイトの基本となるテーマをインストールする。 これはHugo Themesから選べる。 ここではArchie を選んだ(athul/archie Github, Archie Sample)。

$ cd themes
$ git clone https://github.com/athul/archie.git

でテーマのインストールは完了となる。 ここにarchetypes/とconfig.tomlの参考に出来る例があるので適宜コピペする（実際の設定はこちら）。 また後のために.git/などのGitまわりのディレクトリは削除しておく。

Content

content/内での構造は

content/
├── about
├── notes
└── posts

とした。 各々好きなディレクトリ名、構造にすることが出来る。 それぞれに適宜.mdファイルの記事を置いていく。 先述の参考にしたconfig.tomlの内容を見て、上記の構造と合っているかどうか確認する。 ここでの確認においてはcontent/がルートディレクトリになっており、それ以下の構造を考える。

Webページの確認

途中でサイト作成がうまく行っているかのローカル環境での確認は

$ hugo server

で行える。 ブラウザでhttp://localhost:1313/を打ち込めばアクセスできる。 正しい構造になっていればcontent/以下に作成した.mdファイルがWebページとして表示される。

別途Hugoで必要な設定

Githubが対応している静的サイトジェネレータはJekyllなので、Hugoを使う際は別途設定をしなければならない。

まずは<username.github.ioに空ファイルで.nojekyllを作る（無い場合を確認していない。公式にはこう書いてある。）。

次にconfig.tomlに

$ publishDir = "docs"

を追加する。 HugoはGithubの対応が無いため、ローカル環境で

$ hugo

を実行することでhtmlファイルなど一通りのファイルをローカルでビルドする必要がある。 この際、デフォルトでは作成されたファイルはpublic/に保存される。 このディレクトリはGithubで対応されていないため、対応されているdocs/に変更することで読み込まれる。 上述の設定ファイルへの記述はこの対応のためである。

またこのままではHomepageが機能せず、PDFなどのリンクを貼っても機能しない。 これはdocs/以下のファイルを読み込むようにはなっているが、ルートの指定が正しくされていないため、リンクが機能していないためだ。 これを修正するために

canonifyurls = true

をconfig.tomlに追記する。

一通り公開する記事の準備が出来たらhugoでビルドしてdocs/以下にhtmlファイルなどを生成しておく。 PDFファイルなどへのリンクを貼るときはdocs/pdf/のようにディレクトリをつくり、そこにPDF を保存しておく。 リンクは[テキスト](https://<username>.github.io/pdf/ファイル名.pdf)と書いておけばつながる。

Github（リモート）まわりの設定

ローカルでしか設定を行なっていないので、リモートのGithubでの設定を行なう。

Githubで通常どおりリモートリポジトリを作る。 ただしリポジトリ名は<username>.github.ioという名称で作る。 またREADMEやLICENSEなどの設定の選択肢があるが、これらは全て作らないようにしておく。 このとき、デフォルトのブランチ名はmainである。

一方でローカルの<username>.github.ioにて

$ git init

を行なう。 以下通常通りgit add .とgit commit -m "initial commit"を行なう（コミットのメッセージの文言は各々自由）。 次に

$ git remote add origin git@github.com:<username>/<username>.github.io

を行ない、

$ git push -u origin main

することでローカルで行なった設定がGithubに反映される。

リモートリポジトリを作る時にREADMEなどを作ってしまう、あるいはgit実行時にmainとせずmasterとしてしまうとプッシュ（あるいはマージ）が失敗してしまう。 これはヒストリーを共有しない2つの独立なブランチを作ったことによる失敗であり、前者は

$ git push -f origin main

で、後者は

$ git merge --allow-unrelated-histories main master

（Git fatal: refusing to merge unrelated historiesを解決する話）で解決される。 余分なmasterはgit branch -d masterなりgit push --delete origin masterなりで削除。

既にローカルで編集してビルドまで済ませたディレクトリとファイルとがGithubにプッシュされているが、このままではまだhttps://<username>.github.ioにつながらない。

リポジトリ<username>.github.ioのSettingsからGithub Pagesの項目のところへ行き、Sourceの欄で/(root)から/docsへ変更してSaveしておく。 これで自分のサイトへつながるようになっている。