2023-06-14 (Wed)

Windows11でhugoを使用する手順

Table of Contents

Windows11上でHugoプロジェクトをセットアップし、Github Pagesへの自動更新環境を作る方法。

0. Windows11上での事前準備

Windows Updateを全更新の適用完了させる
Microsoft Storeのパッケージアップデート: 左下「ライブラリ」より行える
Microsoft Storeから、Windows Terminalのインストール: Microsoft Storeで「Terminal」で検索
Windows Terminalから、PowerShellを最新版にアップデート: 現時点の最新バージョンは7.3.4

Invoke-Expression "& { $(Invoke-RestMethod https://aka.ms/install-powershell.ps1) } -UseMSI"

Windows Terminalから、chocolateyインストール: ページ中央にあるコマンドをコピーしてTerminalに貼り付けEnter
- chocoコマンドがインストール済みなら、全パッケージアップグレード: choco upgrade all -y (入れてあったパッケージがメンテされなくなった等で更新中断の赤警告がなくなるまで繰り返す)

1. 必要なchocoパッケージのインストール

「 管理者として実行 」によって、Windows Terminal(でPowerShell)を立ち上げる。

「ターミナル」アイコンの上で右クリックすることで、コンテキストメニューを開く

ターミナル上で、以下のコマンドで必要なパッケージをインストールする:

choco install -y git golang hugo hugo-extended vscode

git
golang
hugo
hugo-extended
vscode

記事編集環境としてvscode(Visual Studio Code )を使用する。

vscodeを入れれば、Terminalからは、codeコマンドによって、そのディレクトリを開いたvscodeを立ち上げることができるようになる

2. Visual Studio Codeのセットアップ

(最初は、一度、「Visual Studio Code」アイコンをクリックして立ち上げ、Japanese Language Packや既存エディタ風キーバインドなどの拡張機能をセットアップしておくとよい)

Hugoのためには、以下の拡張機能をインストールしておく:

Better TOML
Hugo Language and Syntax Support
PowerShell
YAML

VSC Extensions

3. Hugoプロジェクトのセットアップ

Githubユーザー(もしくはOrganization)名とリポジトリ名をもとに、HugoプロジェクトのMod ID(github上のプロジェクトのURLに基づくユニーク名)を決める
- github.com/bellbind-trial/hugo-on-windows: 以降のHugoプロジェクト例のMod ID
Hugoプロジェクトにする空ディレクトリを作成する
- hugo-on-windows: Hugoプロジェクト例のディレクトリ名

vscodeを立ち上げ、、Hugoプロジェクトディレクトリを開く: 左上「≡」 -「ファイル」-「フォルダーを開く…」

3.1. vscode内でPowerShellを開く

PowerShellを開くと左の「エクスプローラー」が「COMMAND EXPLORER」に切り替わるので、エクスプローラーに戻しておく

vscode powershell

3.2. PowerShellのターミナル内で`hugo mod init ...`実行

PoserShellのターミナルで、以下のコマンドを実行

hugo mod init github.com/bellbind-trial/hugo-on-windows

(注: Mod IDは各自適切な名前にすること)

hugo mod init

3.3. `hugo.toml`でテーマのModを加えhugo serverを実行

content/フォルダと、テーマのMod IDをセットしたhugo.tomlファイルを作成する
- 例: https://themes.gohugo.io/themes/poison/ : テーマの「Download」のgit URLからMod IDは github.com/lukeorth/poisonを用いる
PowerShellのターミナルで、hugo serverを実行する(hugo serverを実行しているPowerShellウインドウは閉じないこと)

hugo server

hugo mod init

手元のブラウザでhttp://localhost:1313/を開いてWebページが表示されることを確認する。

4. 記事の作成

例として、記事posts/first-post/index.mdを作成する。

この例で記事名をposts/...にしている理由は、これがpoisonテーマが要請するサイト構造だからである。テーマによって構造化に必要な記事名のパターンが存在しているので、説明やソースのexampleSiteを見て調べてから記事を作成すること。

PowerShellの「+」でターミナルを追加する
新たに開いたターミナルで、hugo new posts/first-post/index.mdを実行する

hugo new posts/first-post/index.md

左の「エクスプローラー」から、content/フォルダを開き、index.mdを編集する
ブラウザで記事が追加されていることを確認する

new post

このあと、各テーマの説明ページにしたがって、hugo.tomlを編集し、カスタマイズ(最初に書いた [module] 部分はファイルの一番うしろに置いてよい)し、公開してもよいように調整する。

5.Hugoプロジェクトをgitリポジトリ化する

重要: vscodeの「設定」で、「Files: Eol」を\nに変更 すること。

5.1. `.gitignore` ファイルを作成

.gitignoreファイルの内容:

/public/
/resources/_gen/
/assets/jsconfig.json
/.hugo_build.lock
hugo_stats.json

5.2. `.github/workflows/gh-pages.yml`ファイルを作成

参考: フォルダーのトップのファイルを選び「新しいファイル」でパス名に.github/workflows/gh-pages.ymlを入れれば、親ディレクトリごと作られる

.github/workflows/gh-pages.ymlファイルの内容:

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  pull_request:

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

      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: 'stable'

      - 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@v3
        # If you're changing the branch from main,
        # also change the `main` in `refs/heads/main`
        # below accordingly.
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

(各システムの最新版を使う設定。失敗する場合は、失敗しないバージョンで固定する。)

5.3. gitリポジトリ作成(git initのGUI)

フォルダーにリポジトリ(.git/)がなければ、左の「ソース管理」ボタンを選ぶと、「リポジトリ初期化」ボタンが出てくる
- 「リポジトリ初期化」ボタンを押すと、.git/以下が作られ、以降gitリポジトリ管理の機能が使用可能になる

リポジトリ作成後、PowerShellのターミナルで、git config user.nameとgit config user.emailを設定しておく必要もある。

参考: https://codelikes.com/git-config/

git config user.name "githubで使っているユーザー名"
git config user.email "githubへ登録したメールアドレス"

(globalで設定してあれば不要)

5.4. ステージへのファイルの追加(git addのGUI)

注: 右下にある改行コード(赤囲い部分)は、クリックすれば変更でき、「CRLF」の場合は、追加前に「LF」に変更して「保存」しておく

各ファイルの右の「U」の状態は「更新あり」の意味
「変更」の「+」ボタンで、「U」つきファイルの一括追加ができる
- 各ファイルの「+」ボタンで、個別の追加ができる

5.5. コミット

ステージに追加したファイルは、ファイルの右が「U」から「A」(「追加済み」の意味)になる
追加後、「コミット」ボタンを押すと、COMMIT_EDITMSGファイルの編集が開く
ファイル内にコミットメッセージを埋め、「保存」 する
右上の「✓」ボタンを押すことでコミットが完了する

(より複雑なgit commit --amendのようなものに相当する操作は、「ソース管理」の右の「・・・」の「コミット」メニュー内に存在する)

以降、編集作業は、ファイルの追加や更新をしたあと、変更ファイルのステージ追加(5.5.)とコミット(5.6.)を繰り返すことで行う。

6. github上のgitリポジトリと同期させる

gitリポジトリの内容をgithubへpushする大前提として、github上にアカウントがあり、sshの公開鍵(~/.ssh/id_rsa.pubや~/.ssh/id_ed25519.pubなど)を登録してある必要がある。

詳細は付録Aへ

6.1. github上で空リポジトリを作成

まず、github上に 空のリポジトリ (READMEなし、Licenseと.gitignoreはすべてNone)を作成し、git URL(git@github.com:....)を控えておく

6.2. vscodeへgithubのリポジトリのgit URLを設定

「ソース管理」の右の「・・・」から、「リモート」- 「リモートの追加…」を選ぶ
上に出るinputフォームに、先程のgit URLを設定する

リモートの追加が行われると、コミットしてあれば、「変更の同期」ボタンが出るので、押すとpushされる。

Github Actionsのための.github/workflows/gh-pages.ymlを含めてあるため、「変更の同期」をすれば、githubクラウド上でHTMLファイルが入ったgh-pagesブランチが作られる。

github上の更新を取り込む方法は付録Bへ

6.3. github上のPages設定のブランチ変更

Github PagesでWebサイトを使用できようにするには、初回のpushを行ってHTMLファイルのあるgh-pagesブランチが生成されたあとで、 github上でリポジトリトの「Settings」 - 「Pages」 - 「Branch」で、「gh-pages」に変更する必要がある。

A. githubのssh認証設定方法

以降のコマンド実行は、PowerShellターミナルで行う(vscode内のPowerShell環境でも可)。

ssh関係のコマンドは標準でWindows11に入っている

A.1. 公開鍵生成: `ssh-keygen`

ssh用公開鍵を作成する。いまから作るのであれば、アルゴリズムはrsaよりも ed25519がよい。

ssh-keygen -t ed25519

以降、ファイル名やパスフレーズの入力を求められるが、文字は入れずに、生成がおわるまで全部Enterキーのみ を押しつづける。

以下のファイルが作られる:

~/.ssh/id_ed25519.pub: 公開鍵テキストファイル
~/.ssh/id_ed25519: プライベート鍵テキストファイル(このファイルからはssh-keygen -yコマンドで公開鍵テキストも取り出せる)

A.2. 公開鍵のテキストをクリップボードにコピー: `clip`

Windows11が備えるクリップボードへのコピーを行うコマンドは clip 。

cat ~/.ssh/id_ed25519.pub | clip

このコマンドを実行したら、公開鍵ファイルの内容を、Ctrl+Vで、ブラウザのテキストエリアへ貼り付けられるようになる。

A.3. githubへ公開鍵を登録

サインインしたgithubのWebページの右のユーザーアイコン右の「▽」から「 Settings 」メニューを開き、左のリストの「 SSH and GPG Keys 」を開く。

この設定ページ内の「SSH keys」の右にある「 New SSH key」ボタンを押す。

入力項目が「Title」、「Key type」、「Key」とあるうちの 「Key」テキストエリア に、Ctrl+Vで先ほどコピーした公開鍵テキストを貼り付け、 「Add SSH key」ボタン を押す(Titleは空欄、Key typeは"Authentication Key"のままでよい)。

するとAuthentication Keysに公開鍵が追加される。この結果、このマシンから、githubへpushすることができるようになる。

B. github上の更新をvscodeで反映させる方法

「同期」をすれば、リモートの更新をローカルへ反映させることができる。

vscodeには、「同期」実行の２つのUIがある。

「ソース管理」のメニューから「同期」を選ぶ
左下の「🔄」を押す