🍑

Github ActionsとHugoを使って簡単に静的サイトを建てる

2024/10/30に公開

GitHub Actions

GitHub Pages

Hugo

tech

Githubには、静的サイトをホスティングできるGithub Pagesという機能と、CI/CDツールのGithub Actionsという機能がある。

Githubの機能とHugoを使って簡単に静的サイトを作成してみる。
※ Github Pagesを使うには、Publicリポジトリにする必要があります。

使用環境

➜  ~ hugo version
hugo v0.130.0-9b1b11c8a59a900458e9e460f197a44367c022ee+extended linux/amd64 BuildDate=2024-07-29T13:51:56Z VendorInfo=gohugoio
➜  ~ uname -a
Linux XXXXXXXXXX 5.15.153.1-microsoft-standard-WSL2 #1 SMP Fri Mar 29 23:14:13 UTC 2024 x86_64 x86_64 x86_64 GNU/Linux

ローカルで静的サイトを作成する

hugoがインストールされてない場合は、インストールする。公式サイト参照。

自分の場合は、brew install hugo とかで入れた。

まずは、ローカルでhugoを使って静的サイトを準備する。

➜  ~ hugo new site hugo-test2
Congratulations! Your new Hugo site was created in /home/red/hugo-test2.

Just a few more steps...

1. Change the current directory to /home/red/hugo-test2.
2. Create or install a theme:
   - Create a new theme with the command "hugo new theme <THEMENAME>"
   - Or, install a theme from https://themes.gohugo.io/
3. Edit hugo.toml, setting the "theme" property to the theme name.
4. Create new content with the command "hugo new content <SECTIONNAME>/<FILENAME>.<FORMAT>".
5. Start the embedded web server with the command "hugo server --buildDrafts".

See documentation at https://gohugo.io/.
➜  ~ cd hugo-test2
➜  hugo-test2 ls
archetypes  assets  content  data  hugo.toml  i18n  layouts  static  themes

git init しておく。

➜  hugo-test2 git init
Initialized empty Git repository in /home/red/hugo-test2/.git/

Hugoに使うtheme(テーマ)を選ぶ。上記のメッセージのように自分で作成してもいいし、他のテーマをインストールしてもよい。今回はhugo-bookを使う。
インストール後、hugo.tomlに使用するテーマを追記する。

➜  hugo-test2 git:(main) ✗ git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book
Cloning into '/home/red/hugo-test2/themes/hugo-book'...
remote: Enumerating objects: 4678, done.
remote: Counting objects: 100% (1228/1228), done.
remote: Compressing objects: 100% (370/370), done.
remote: Total 4678 (delta 930), reused 945 (delta 825), pack-reused 3450 (from 1)
Receiving objects: 100% (4678/4678), 9.01 MiB | 961.00 KiB/s, done.
Resolving deltas: 100% (2426/2426), done.

➜  hugo-test2 git:(main) ✗ echo "theme = 'hugo-book'" >> hugo.toml

この時点でhugo serverを動かせば、ローカルで確認することができる。

➜  hugo-test2 git:(main) ✗ hugo server
Watching for changes in /home/red/hugo-test2/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /home/red/hugo-test2/hugo.toml
Start building sites …
hugo v0.130.0-9b1b11c8a59a900458e9e460f197a44367c022ee+extended linux/amd64 BuildDate=2024-07-29T13:51:56Z VendorInfo=gohugoio


                   | EN
-------------------+-----
  Pages            |  8
  Paginator pages  |  0
  Non-page files   |  0
  Static files     | 78
  Processed images |  0
  Aliases          |  2
  Cleaned          |  0

Built in 21 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

ブラウザで http://localhost:1313/にアクセス

テスト用にとりあえずトップページを作る

➜  hugo-test2 git:(main) ✗ hugo new content content/_index.md
Content "/home/red/hugo-test2/content/_index.md" created

content/_index.md

---
title: "Introduction"
date: 2024-10-30T10:56:12+09:00
draft: false
---
## Introduction

This is **bold** text, and this is *emphasized* text.

Visit the [Hugo](https://gohugo.io) website!

hugo new contentで生成されるテンプレートが上記と異なる場合がある。

公式の説明によると、次の優先順位でファイルを参照し、これらがいずれも存在しない場合に組み込みのデフォルトのテンプレートを作成するらしい。なので、上記と異なる場合は、以下のファイルを確認しよう。

archetypes/posts.md
archetypes/default.md
themes/my-theme/archetypes/posts.md
themes/my-theme/archetypes/default.md

再度hugoを立ち上げて、ブラウザでアクセス

Github上でサイトを公開する

最初にGithubでリポジトリを作成しておく。

リポジトリの設定を変える
[Settings] -> [Pages] -> Build and deployment
Branchをmainにする

パーミッションを変更する
[Settings] -> [Actions] -> [General] -> Workflow permissions

.gitignoreの設定

.gitignore

# Generated files by hugo
/public/
/resources/_gen/
/assets/jsconfig.json
hugo_stats.json

# Executable may be added to repository
hugo.exe
hugo.darwin
hugo.linux

# Temporary lock file while building
/.hugo_build.lock

hugo.tomlの設定
細かい設定については、hugoの公式サイトやhugo-bookを参照してください。
baseURLやBookRepoなどはご自身のリポジトリ名やユーザー名に適宜置き換えてください。

hugo.toml

baseURL = 'https://wild0ni0n.github.io/hugo-test2/'
languageCode = 'ja'
defaultContentLanguage = 'ja'
title = 'テストサイト|タイトル'
theme = 'hugo-book'
enableGitInfo = true
[params]
  BookRepo = 'https://github.com/wild0ni0n/hugo-test2'
  BookCommitPath = 'commit'
  BookServiceWorker = true

workflowを作成する

➜  hugo-test2 git:(main) ✗ mkdir -p .github/workflows && touch .github/workflows/gh-pages.yml
➜  hugo-test2 git:(main) ✗ vim .github/workflows/gh-pages.yml

.github/workflows/gh-pages.yml

name: GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0

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

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'

ファイルをコミットして、Githubのリモートリポジトリにpushする

➜  hugo-test2 git:(main) ✗ git add .gitignore
➜  hugo-test2 git:(main) ✗ git add .github
➜  hugo-test2 git:(main) ✗ git add *
➜  hugo-test2 git:(main) ✗ git commit -m "1st commit"
[main (root-commit) 74b61b2] 1st commit
 7 files changed, 76 insertions(+)
 create mode 100644 .github/workflows/gh-pages.yml
 create mode 100644 .gitignore
 create mode 100644 .gitmodules
 create mode 100644 archetypes/default_bak.md
 create mode 100644 content/_index.md
 create mode 100644 hugo.toml
 create mode 160000 themes/hugo-book
➜  hugo-test2 git:(main) git remote add origin git@github.com:wild0ni0n/hugo-test2.git
➜  hugo-test2 git:(main) git push -u origin main

pushすると二つのワークフローが実行される。
pages build and deploymentでエラーが出る可能性があるが今は無視する。

Deployのワークフローが完了していると、gh-pagesブランチが出来ているので、リポジトリの設定を変える。
[Settings] -> [Pages] -> Build and deployment
Branchをgh-pagesにする

pages build and deploymentが再度動くのでしばらく待つ。
成功すると、github pages上にサイトが公開される

ブラウザでアクセス

終わり 😎

余談

リンクプレビューを修正する
Slackで貼ったとき、リンクプレビューが微妙。

コンテンツを書く時は、titleやdescriptionをちゃんといれよう

_index.md

---
title: "Introduction"
description: "ASM導入検討を進めるためのガイダンス（基礎編）"
weight: 1
---
...

修正後

使用環境

ローカルで静的サイトを作成する

Github上でサイトを公開する

余談

Discussion