Hugo + GitHub で静的サイトを作る（mac編）

2021年2月11日 Hugo

とりあえずHugo＋GitHubにより作成した記事がネット閲覧可能となるまでの最短と思われる手順を示す。

前提条件

・GitHubアカウント作成済み
・PCにgit, hugo導入済み (hugo導入はこちらを参照)
・macターミナルの初歩的な操作ができること
・gitの初歩的な運用を理解していること

GitHubでの作業(1)

1. GitHubにリポジトリ作成
名称は "{ユーザ名}.github.io" であること。
これでGitHub Pagesが使える。

**（注）リポジトリの最初の部分がユーザー名と完全に一致しない場合は機能しない**

ローカルでの作業

2. 静的サイトのテンプレート作成
hugo new site {ユーザ名}.github.io
{ユーザ名}.github.ioディレクトリが作成され、その配下にテンプレートが自動作成される。

3. ローカルリポジトリの作成
{ユーザ名}.github.ioディレクトリにローカルリポジトリを作成する。
ex) git init

4. テーマを取得する
Hugo Themesサイトから適当に選んで取得する。GitHubで管理されているので、git submoduleで取得できる。themesディレクトリに適当な名称（下の例では"ananke"）を指定して取得する。
ex) git submodule add https://github.com/budparr/gohugo-theme-ananke.git ananke

**anankeディレクトリが自動作成され、その配下にテーマテンプレートが取得される**

5. config.tomlの編集
{ユーザ名}.github.ioディレクトリのconfig.tomlを開いて、以下のように編集する。
①baseURL = “https://{ユーザ名}.github.io/” ←rootのパスを指定
②theme = "ananke" ←使用テーマを指定（「4. テーマを取得する」で作成したもの）
③publishDir = "docs" ←公開用ページの格納先を指定

③について、GitHub Pagesでは公開用ページ格納先はdocsというルールになっているらしく、この設定は必須。

6. 記事の作成
hugo newコマンドにより、contentディレクトリにマークダウン形式のテンプレート記事を作成する。作成されたファイルはデフォルトで下書き設定となっているので、公開用に変更する。
hugo new post/test.md
vi content/post/test.md
draft: true → falseに変更

**hugo newによりcontentディレクトリに記事テンプレートが作成される**

**記事テンプレートの編集後。下の方に「Hello, world!」を追加してみた。**

7. 公開用ページの生成（ビルド）
hugoを叩くとdocsディレクトリが自動作成され（config.tomlのpublishDir = "docs"の設定したことによる）、その中に公開用ページが作成される。

8. ローカルでの表示確認
hugo serverコマンドによりローカルサーバーが起動する。ターミナルに出力されたhttp://localhost:1313/をブラウザで表示して確認できる。

Ctrl+C でサーバープロセスをkillする

9. GitHubにプッシュ
インターネットに公開するべく、作成したファイルをGitHubに転送する。リモート指定（git remote addコマンド）は最初の１回だけでOK。
git add .
git commit -m “first commit”
git remote add origin https://github.com/j9KBLx6V/j9KBLx6V.github.io.git
git push -u origin master

GitHubでの作業(2)

10. GitHub PagesのSourceをdocsに変更
Settings → GitHub Pages → Source とたどり、デフォルトの/(root)を/docsに変更してSaveする。

11. インターネットでの表示確認
https://{ユーザ名}.github.io/にアクセスして、ローカルサーバで表示したものと同様になっていることを確認。

ケアレスミスと原因

基本は、何かしら追加・修正したら、ビルドしてGitHubにプッシュすること。

・記事を作成したのに表示されない
原因：ビルドした？（参照：7. 公開用ページの生成（ビルド））

・ローカルでは表示されるがインターネットでは表示されない① 404 not found
原因：記事内の draft を falseに変えていない。（参照：6. 記事の作成）

・ローカルでは表示されるがインターネットでは表示されない②
原因：config.tomlでpublishDir = "docs"を追加していない。（参照：5. config.tomlの編集）

・さらに記事を追加したが、表示されない。
原因：公開用ページ生成のコマンドを叩かずにGitHubにプッシュした。（参照：7. 公開用ページの生成（ビルド）、9. GitHubにプッシュ）

最初からやり直したい場合

色々いじっているうちに訳が分からなくなり、とりあえず全ての作業を最初から行いたい場合、GitHubのリポジトリとローカル環境を丸ごと削除する。私もこの記事を作成するにあたり、何度もこの作業を繰り返した。 GitHubのリポジトリ削除は、Settingsの最下部にあるリポジトリ削除ボタンを押して進める。

ローカルの削除は、rm -rfコマンドにてディレクトリを丸ごと削除でOK。

参考サイト

GitHub Pages公式サイト：https://pages.github.com/
Hugo Themes：https://themes.gohugo.io/