Hugo + GitHub Pages + 無料で洒落たブログを30分で作る

# Links
### Hugo
https://gohugo.io/
特に説明は書きませんが、おしゃれな静的サイトをすぐに作れるやつです。
例えばブログだと以下の様に、マークダウンで記事を書いて、コマンドを実行すると公開用ファイルが生成されるのでそれをアップロードすると簡単に公開できるというもの。

```
本体
 ├── 設定ファイル
 ├── マークダウンで書いた記事
 └── 公開用ファイル
```

### Hugo themes
https://themes.gohugo.io/
今回は[hello-friend-ng](https://themes.gohugo.io/hugo-theme-hello-friend-ng/)というテーマを使わせて頂く事にしました。

### Host on GitHub - GitHub Project Pages
https://gohugo.io/hosting-and-deployment/hosting-on-github/#github-project-pages

# 想定の構成
今回は、本体ごとGitHubにあげて、特定のディレクトリ配下だけを自動的にGitHub Pagesとして公開する方法を試すことにしました。

* 公開URL
`https://<アカウント>.github.io/<リポジトリ名>`

* 本体をprivateリポジトリにしたかったが...
  * 現状、無料のprivateリポジトリだとGitHub Pages 使えなかった。
             下書きもあるので出来れば本体はprivateで管理したかったがしょうがなくpublicにした。本体と公開用リポジトリを別で管理すれば良いのだけど、今回はやらない。    

すでに、たくさんの有用な記事があり、ドキュメントもしっかりしているので特に書くこともないのですが、1ヶ月の自分のために残す事にしました。

# 公開までの作業
### プロジェクト作成
```shell-session
$ brew install hugo
$ cd /path/to/好きなディレクトリ
// blogディレクトリ下にHugoを作っていきます
$ hugo new site blog
// いろいろなファイルができてます
$ ls blog
archetypes/ config.toml content/ data/ layouts/ resources/ static/ themes/
```

### リポジトリ作成
先に、GitHub上で空のリポジトリ(ここでは `blog`)を作り、リモートURL登録

```shell-session
$ cd blog
$ git remote add origin https://github.com/yotasasaki/blog.git
```

### テーマをSubmoduleで登録
GitのSubmodule管理にしておくとテーマ作成者の変更を後々簡単に反映できるので、今回はそうした。

```shell-session
$ git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng
// いろいろなファイルができてます
$ ls themes/hello-friend-ng 
```

### 設定ファイル書き換え
1. まずはテーマ作成者の指示書([How to configure](https://themes.gohugo.io/hugo-theme-hello-friend-ng/#how-to-configure))を読みます。
  * 「Just copy:...」 に従って、blog/直下にある `config.toml`を上書きします。

2. もう少し様々な設定パターンを見たいときは、`exampleSite` に置いてある `config.toml`を見ると、参考にできます。 [GitHubにも公開されています](https://github.com/rhazdon/hugo-theme-hello-friend-ng/blob/b9fd0dbe9b2c6d0a42d7ac6deaa17c2e8d2cf2f6/exampleSite/config.toml)

3. [Configure Hugo](https://gohugo.io/getting-started/configuration/)も参考にできます。

とりあえず変更したのは以下。

* baseUrl
    * `https://<アカウント>.github.io/blog` がTOPページになる想定なので、書き換え
* piblishDir
    * 本来は公開用ファイルは `public/`に出力されるが、　ここでは[GitHub Project Pages](https://gohugo.io/hosting-and-deployment/hosting-on-github/#github-project-pages) の従って、`docs/`に出力される様に変更。最近また変わったんですかね。こうしておくと、本体ごとmasterブランチにpushしてしまえば、GitHub Pagesで(許可設定さえすれば)自動的に`docs/`だけがサイトとして公開されるみたいです。すごい。 [GitHub Pages documentation](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch)

```diff
< baseurl = "/"
---
> baseurl = "https://<アカウント>.github.io/blog"
> publishDir = "docs"


23,24c24,25
<     title = "Hello Friend NG"
<     subtitle = "A simple theme for Hugo"
---
>     title = "好きなブログタイトル"
>     subtitle = "好きなサブタイトル"


<       logoHomeLink = "/"
---
>       logoHomeLink = "/blog"

// ロケールに基づいた上部メニュー設定? 自分はすぐ下の設定の、generic menuを活かしたかったので
// ここはコメントアウトしました。
<     [languages.en.menu]
<       [[languages.en.menu.main]]
<         identifier = "about"
<         name = "About"
<         url = "/about"
<       [[languages.en.menu.main]]
<         identifier = "showcase"
<         name = "Showcase"
<         url = "/showcase"
---
> #    [languages.en.menu]
> #      [[languages.en.menu.main]]
> #        identifier = "about"
> #        name = "About"
> #        url = "/about"
> #      [[languages.en.menu.main]]
> #        identifier = "showcase"
> #        name = "Showcase"
> #        url = "/showcase"

```

### ローカルサーバーで動作確認
```
$ hugo server -t hello-friend-ng --watch
```
http://localhost:1313/blog/
で、確認できればOKです。変更がリアルタイムに反映されるので、エディタとブラウザ並べて表示しておくと便利です。

<img width="872" alt="スクリーンショット 2019-06-30 18.38.37.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/87716/0ed78f76-1b86-8288-9793-598e8ed64c84.png">

### 記事作成
* `posts/` 下にファイルを作ります。これは`config.toml`上の以下の設定に従うためです。
`[[menu.main]] url = "/posts"`

```
$ hugo new posts/first-article.md
/path/to/blog/content/posts/first-article.md created
```

##### Front matterを書き換えます
* draft: false にします。これしないと公開用ファイルが生成されない
* tagsはそれっぽいのを適当に作成
* [Front Matter](https://gohugo.io/content-management/front-matter/)のドキュメントも参照してください

```
---
title: "はじめまして"
date: 2019-06-30T02:34:27+09:00
draft: false
toc: false
images:
tags:
  - daily
---

Hugoで簡単なブログを作りました。
```

### Aboutページの作成
```shell
$ hugo new about.md
```
同様に、Front matterを書き換えます。

### 公開用ファイルの生成
```
$ cd blog/
$ hugo
$ ls docs/
// 公開用ファイル群が生成されてる
```
簡単！

### GitHub Pagesにて公開
まず、GitHubリポジトリのSettingsタブから、Sourceを `master branch/docs folder` に変更します。
これで、本体をmasterブランチにpushすればその、docsディレクトリの中身だけがGitHub Pagesとして公開されるようになります。先程 `config.toml`でpublishDirを変更したのはこの為です。

<img width="745" alt="スクリーンショット 2019-06-30 18.54.33.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/87716/e2452fa2-c645-4571-a68b-55113ee2ad39.png">


### GitHubにpush
```
$ git push origin master
```
https://<アカウント名>.github.io/blog/

に公開されていればOK。

以上です。

# 注意点やコツ
* キャッシュ
    * 分かっていてもブラウザキャッシュで変わらない事にアレってなりがちなので、ハードリロードする。
    * GitHub側でもキャッシュを持っているのか、正しい設定に直したはずが実際のリンク先がおかしい、みたいな事があり悩んだが10分〜くらい放置したら治ってた...そういうのツライ。
* baseUrl
    * httpから始まるURLにしないと( `/blog` とかだと)、`hugo server` が機能しなかった
    * `http://localhost:1313`で404エラー
* テーマを使う場合は、テーマごとの指示をよく読む
    * exampleSiteのconfig.tomlも参考にする

# 今回やらなかったこと
* 本体と公開用フォルダの別リポジトリ管理
    * 本体を別のprivateリポジトリにおき、公開用ファイルだけ本リポジトリで管理するとか?
    * `git worktree` で管理する方法も紹介されていたが、多分意味ない
* ドメインの取得
    * Freenomを使えば無料ドメインが使えて、設定も簡単だがまぁそこまでしなくていいか〜

　
テーマがいろいろあって悩んだり、ちょいとハマったりすると30分では厳しいんですが、同じ構成なら次は30分もかからないはず....！


# 追記(2022/01)
* faviconの追加
    * テーマのリポジトリ内を`favicon`で検索したところ[ドキュメントがあり](https://github.com/rhazdon/hugo-theme-hello-friend-ng/blob/master/docs/favicons.md)、指定のサービスで作成した画像をstatic/配下に配置せよ、とのことで、ちゃんと動作もしました。ただ、はじめは変わらず...?となりましたが[このIssue](https://github.com/rhazdon/hugo-theme-hello-friend-ng/issues/31)をみてブラウザキャッシュをクリアしたところ正常に適用されました。