Hugo + GitHub で静的サイトを作る(mac編)

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

前提条件

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

GitHubでの作業(1)

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

右上のNew repositoryから進める
(注)リポジトリの最初の部分がユーザー名と完全に一致しない場合は機能しない

最下部にあるボタンを押す

ローカルでの作業

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

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

.git(リポジトリ)が作成されていることを確認

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というルールになっているらしく、この設定は必須。

変更前(hugo new siteで作成されたデフォルト状態)
変更後

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する
指定のURLをブラウザで表示。作成した記事が表示されることを確認。

9. GitHubにプッシュ
インターネットに公開するべく、作成したファイルをGitHubに転送する。リモート指定(git remote addコマンド)は最初の1回だけで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

git add と git commit を実行
git remote add と git push を実行

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の最下部にあるリポジトリ削除ボタンを押して進める。

Settingページの最下部にリポジトリ削除ボタンがある
赤線部を枠内にコピペして、下の赤字のボタンを押す。
GitHubアカウントのパスワードを入力して、下の緑ボタンを押して削除完了。

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

rm -rf で作成したサイトディレクトリを強制削除する

参考サイト

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