HugoとGitHub Pagesでサイトを作る (備忘録)

# Hugoとは

[Hugo](https://gohugo.io/)は、Goで書かれたSSG(Static Site Generator)。

- *The world’s fastest framework for building websites* ということで、とにかくビルドが早い (模様)。
- GitHub Pagesと連携して簡単にサイトを作成することができる
- Kubernetesの公式ドキュメントも使っている ([Kubernetesのドキュメント
](https://github.com/kubernetes/website/blob/main/README-ja.md))

# 内容
- 基本は[QuickStart](https://gohugo.io/getting-started/quick-start/) をベースに
- GitHub Pagesの設定をして公開 (https://nakamasato.github.io/hugo-sample)
- Google Analyticsの設定

# hugoのインストール

Macの場合 brewでインストール可

```
brew install hugo
```

# サイト作成

## 1. hugoを初期化

### 新しくプロジェクトを作成する場合 (Dirも作成したい場合)

```bash
hugo new site hugo-sample
git init # Gitで管理することが多いはずなのでgit initしておく
```


### 既存のProjectに追加する場合

既存Directoryに入って `--force`を使えばよい。 (以下の例では、docsの下に今回作成するサイトをまとめておきたい場合。そうでない場合は、 `.`直接CurrentDirを指定すれば良い)

```bash
cd /path/to/your/repo
hugo new site docs --force
```

何れにせよ、以下のような結果が出るので、基本は示された3つのステップを行っていくだけ。

```bash
Congratulations! Your new Hugo site is created in /Users/masato-naka/repos/nakamasato/hugo-sample.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.
```

この時点でこのようにdirectoryとファイルが作成される

```
tree .
.
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

6 directories, 2 files
```


## 2. Themeを追加

submoduleとして、 `themes` 以下に themeを配置。(今回はこちら: https://themes.gohugo.io/themes/hugo-whisper-theme/)

```bash
git submodule add https://github.com/zerostaticthemes/hugo-whisper-theme.git themes/hugo-whisper-theme
```

- Submoduleではなくcloneでも可
- 既存のプロジェクトでdocs以下にサイトの情報は全て入れたい場合は、 submoduleの先を `docs/themes/hugo-whisper-theme`などにするといい

```
± tree -L 3
.
└── docs
    ├── archetypes
    │   └── default.md
    ├── config.toml
    ├── content
    ├── data
    ├── layouts
    ├── static
    └── themes
        └── hugo-whisper-theme

8 directories, 2 files
```

## 3. exampleSiteを使って試す

```bash
cp -a themes/hugo-whisper-theme/exampleSite/. .
```

docsの中にthemesを入れていても、gitのrootDirに入れていても同様にできる。

## config.tomlの更新
`themesDir`: 上で `themes`以下に themeをおいたので変更する

```toml
themesDir = "themes"
```

## 4. ローカルで実行

```bash
hugo server -D # -D include content marked as draft
```

http://localhost:1313/ で確認できるようになる

![スクリーンショット 2021-12-23 6.44.36.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/423fbdad-1aac-6fa5-e8b7-0e7fa22b5e68.png)

## 5. 自分でファイルを変更して自分用にする

- config.toml
- contents

などを更新して自分のサイトを作成

## 6. GitHub Pagesなどで公開

### GitHub Actionsを追加

https://github.com/peaceiris/actions-hugo こういう便利なものがあるのでこちらを使用。

```yaml:.github/workflows/github-pages.yml
name: github-pages

on:
  push:
    branches:
      - main  # Set a branch to deploy
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-20.04
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.88.0'
          extended: true

      - name: Build
        # working-directory: docs # docs以下にsiteをおいた場合
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public # docs以下にsiteをおいた場合　./docs/publicに変更が必要
```

`if: ${{ github.ref == 'refs/heads/main' }}` は一度PR時にコメントアウトして、GitHub Actionsが `gh-pages`というブランチにBuild後の結果をPushできていることを確認してから戻すと、mainブランチにPush後に公開できてないのを発見することが減る。


### GitHub Pagesの設定

![スクリーンショット 2021-12-23 7.41.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/0a840e2b-6b9a-9de2-49d9-5c23cd262906.png)

- 今回は、 `gh-pages`ブランチの root以下 (GitHub Actionsの出力がRoot以下なので)を指定。
- `config.toml`の`baseURL`を自分のrepoの名前 `<github account>.github.io/<repo>`など書く。custom domainの場合は設定をすでにしてあれば、 `<custom domain>/<repo>`のように書ける

https://nakamasato.github.io/hugo-sample でもcustom domainに飛ぶようにできた!

![スクリーンショット 2021-12-23 7.53.27.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/2963b71e-a000-2855-a32e-1f8c2b35f5a7.png)

## 7. Google Analyticsを設定

Google Analyticsから設定情報を取得 (今回はGA4)

![スクリーンショット 2021-12-23 8.03.48.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/59525125-d07b-5922-d36b-f40fc75a2e2e.png)


![スクリーンショット 2021-12-23 8.01.40.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/9c40542d-56f3-3dec-3e88-35509b4bc869.png)

[Configure Google Analytics](https://gohugo.io/templates/internal#configure-google-analytics)にもあるが、[https://github.com/gohugoio/hugo/releases/tag/v0.82.0](v0.82.0)以降では、 [Add support for Google Analytics v4 ba16a14c @djatwood](https://github.com/gohugoio/hugo/pull/8287) がマージされていて単純に `googleAnalytics`に設定すれば良くなっている。

が、テーマによって使っているtemplateが違う可能性があるので、今回使ってthemeだと
[google-analytics.html](https://github.com/zerostaticthemes/hugo-whisper-theme/blob/master/layouts/partials/google-analytics.html)のように、`.Site.Params.google_analytics_id`で指定する用になっていた。(詳細は調べていない)

```html
{{- if .Site.IsServer -}}
  <!-- Dont add Google analytics to localhost -->
{{ else }}
  {{ $gid := (getenv "HUGO_GOOGLE_ANALYTICS_ID") }}
  {{ if $gid }}
    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id={{- $gid -}}"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', '{{- $gid -}}');
    </script>
  {{ else }}
    {{ if .Site.Params.google_analytics_id }}
      <!-- Global site tag (gtag.js) - Google Analytics -->
      <script async src="https://www.googletagmanager.com/gtag/js?id={{- .Site.Params.google_analytics_id -}}"></script>
      <script>
        window.dataLayer = window.dataLayer || [];
        function gtag(){dataLayer.push(arguments);}
        gtag('js', new Date());
        gtag('config', '{{- .Site.Params.google_analytics_id -}}');
      </script>
    {{ end }}
  {{ end}}
{{ end }}
```

デプロイして、GA上で確認 (baseURLの設定を間違えて 404が何回か出たが取れるようになった。)　

![スクリーンショット 2021-12-23 8.52.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/7059/ca4b3717-2b78-4e28-955a-7b2a63238052.png)

# ToDo

- analytics.jsがまだ読み込まれてるっぽいので原因確認

# 参考Links

- [GitHub Actions for Hugo](https://github.com/peaceiris/actions-hugo)
- [Hugoサイトに最新版のGoogle Analyticsのタグを埋め込む
](https://helve-blog.com/posts/web-technology/hugo-google-analytics-tag/)
- [Hugoで未だ対応していないgtag.jsを利用して Googleアナリティクスする](https://qiita.com/momotaro98/items/4de7934fd79cd6b34fce)
- [Migrate from analytics.js to gtag.js (Universal Analytics)](https://developers.google.com/analytics/devguides/migration/ua/analyticsjs-to-gtagjs)
- [hugo sample (github repo)](https://github.com/nakamasato/hugo-sample)
- [今回作ったサイト](https://nakamasato.github.io/hugo-sample)