Hugoの使い方メモ

2020-09-14 hugo

よく使うコマンド

1# posts/ にポストを作成
2hugo new posts/{ポスト名}.md
3
4# 確認用のサーバーを立てる
5hugo serve -D

注意

2020/09/22時点で、テーマをClarityから、自作のものに変更したため、現在はClarityテーマを使用していない。しかし、Clarityテーマの導入方法としての情報を残すために、記事の内容は一部そのままにしてある。

Hugoとは

静的サイトジェネレータと呼ばれるソフトウェアの一種
Go言語で作られているため、ビルドが高速らしい
この技術ブログもHugoで作成したもの ~~(Clarityテーマを使用)~~ (自作テーマを使用)

インストール

MacやLinuxなら、 homebrew(linuxbrew)でインストールできる。

1brew install hugo

サイトの作成方法

hugo new site {サイト名} で新規にサイトを作成できる。このコマンドを実行すると、ここで指定したサイト名と同名のディレクトリが作成される。

例)

1hugo new site memo

テーマの追加

以下のコマンドを実行することで、すでに誰かが作ってくれているテーマを追加できる。

1cd {サイト名} # サイトのディレクトリへ移動
2git init
3git submodule add {テーマがあるリポジトリのURL} themes/{テーマの名前}

追加したテーマを使用するためには、サイトのディレクトリのルートにある config.toml (Hugoの設定ファイル) に以下の内容を追記する。

1theme = "{テーマ名}"

今回はClarityというテーマを使ったので以下の手順を行った。

参考: https://github.com/chipzoller/hugo-clarity#getting-up-and-running

1cd memo
2git init
3git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity
4cp -a themes/hugo-clarity/exampleSite/* . # ← config.tomlとかもexampleSiteをそのまま流用した

コンテンツの追加

以下のコマンドを実行すると、 content/posts/{ファイル名}.md というファイルが自動生成される。このファイルを編集していけば良い。

1hugo new posts/{ファイル名}.md

注意)

ファイルの先頭にあるヘッダ(Front-matterという) で draft を false にしておかないと、ビルド時に反映されない。

1---
2title: "Hugoの使い方メモ"
3date: 2020-09-14T22:45:24+09:00
4draft: false
5tags: ["hugo"]
6---
7↑ ファイル先頭にこんなのがある。

サーバの起動

以下のコマンドで、ビルド結果の確認用のサーバを起動できる。

1hugo server -D

コマンド実行後、以下のようなメッセージがコンソールに表示されている。

 1                   | EN
 2-------------------+-----
 3  Pages            | 17
 4  Paginator pages  |  0
 5  Non-page files   |  0
 6  Static files     | 61
 7  Processed images |  0
 8  Aliases          |  6
 9  Sitemaps         |  1
10  Cleaned          |  0
11
12Built in 52 ms
13Watching for changes in /home/hrhr49/ghq/github.com/hrhr49/memo/{archetypes,content,data,layouts,static,themes}
14Watching for config changes in /home/hrhr49/ghq/github.com/hrhr49/memo/config.toml
15Environment: "development"
16Serving pages from memory
17Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
18Web Server is available at http://localhost:1313/memo/ (bind address 127.0.0.1)
19Press Ctrl+C to stop

このURL(下から二行目)にブラウザからアクセスすればページを確認できる。

ビルド

以下のコマンドを実行すると、 public/ ディレクトリにビルド生成物ができあがる。

1hugo

GitHub Pagesを使用してデプロイ

GitHub Pagesを使用すれば、GitHubで管理している静的ファイル(HTMLやJavaScriptなど)をホスティングできるので便利。

補足)

静的サイトのホスティングはnetlifyの方が色々と便利そう。しかし、今回はとりあえずGitHubで完結できるメリットを考慮してGitHub Pagesを使うことにした。

ベースURLの設定

confit.toml を修正して baseurl を修正する必要がある。今回は、https://hrhr49.github.io/memo/ URL以下にファイルが配置されるので以下の設定にした。

1baseurl = "https://hrhr49.github.io/memo/"  # Include trailing slash

注意：

今回は後述のGithut Actionsの設定により、 public/ ディレクトリではなくルートディレクトリにビルド生成物を配置するようにした。このような理由から、 baseurl には public/ を含めていない。

GitHub Actionsの設定

以下のGitHub Actionsでは、Hugoのビルド結果をgh-pagesブランチのルートディレクトリに自動で配置してくれるっぽい。

https://github.com/peaceiris/actions-hugo

ただし、今回の場合はワークフローファイルの設定を以下のように変更した。

アクションのトリガとなるブランチ名を main から master に変更した(masterブランチで管理していたため)。
actions-hugo@v2 のオプションとして、 extended を true に変更した。

以上の設定すると、以下の作業を自動でできるようになった。

masterブランチにpushされると、アクションが起動
Hugoのビルドを行い、その生成物を gh-pages ブランチのルートディレクトリに配置 & コミットする。
1. で gh-pages ブランチの内容を変更したので、 GitHub Pages でホスティングしているページも自動で更新する。

GitHub Pagesの設定

以下の内容を実施すればよい。 GitHub Pages サイトの公開元を設定する

つまずいたこと

content/posts/ に追加したはずのファイルがビルド後の public/ フォルダには反映されない現象に悩まされた。

よくソースを見直してみると、 content/post/_index.md というファイル(clarityテーマのexampleからコピってきたファイル)が存在していた。このファイルの中で以下の記載があったため、 content/posts/ の内容が反映されていないみたいだった...。

1+++
2# ↓ この設定のせいで、postsがpostにエイリアスされているため、
3# postsディレクトリの内容が反映されなかった。
4aliases = ["posts", "articles", "blog", "showcase", "docs"]
5title = "Posts"
6author = "Hugo Authors"
7tags = ["index"]
8+++

参考

Categories: