Hugoを初めて使った話

Hugo公式から出ているクイックスタートをやってみます。
基本クイックスタートに沿って実施していくだけです。
クイックスタートの実行結果も見たい！という人はご覧ください。
※とりあえず、うごかすを目的にしているため、詳しい解説は省いてます。。

環境

Ubuntu　20.4

前提条件

hugoのインストール

以下のサイトからLinuxのページを確認。

いろんな方法が書かれてますが、sudo snap install hugoでインストールしました。
aptで入れると古いバージョンが入り上手く動かなかったのでsnap

ubuntu:~$ sudo snap install hugo
hugo 0.145.0 from Hugo Authors installed
ubuntu:~$ hugo version
hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended linux/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=snap:0.145.0
ubuntu@public-instance-tokunaga-ubuntu2:~$ 

gitのインストール

gitはもともとインストールしていたので、ここでは割愛します。

ちなみにバージョンは以下でした。

ubuntu:~$ git --version
git version 2.25.1

サイトを作成する

ディレクトリ作成

ubuntu:~$ hugo new site quickstart
Congratulations! Your new Hugo site was created in /home/ubuntu/quickstart.

Just a few more steps...

1. Change the current directory to /home/ubuntu/quickstart.
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/.
ubuntu:~$ 

これでquickstartというフォルダが作成されました。
lsコマンドでも確認できます。作成したフォルダにcdします。

ubuntu:~$ cd quickstart/
ubuntu:~/quickstart$ 

git周りの事前準備

現在のディレクトリに空の Git リポジトリを初期化

ubuntu:~/quickstart$ git init
Initialized empty Git repository in /home/ubuntu/quickstart/.git/
ubuntu:~/quickstart$ 

Anankeテーマをディレクトリにクローンし 、それをGit サブモジュールthemesとしてプロジェクトに追加

ubuntu:~/quickstart$ git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
Cloning into '/home/ubuntu/quickstart/themes/ananke'...
remote: Enumerating objects: 3915, done.
remote: Counting objects: 100% (440/440), done.
remote: Compressing objects: 100% (195/195), done.
remote: Total 3915 (delta 358), reused 268 (delta 243), pack-reused 3475 (from 3)
Receiving objects: 100% (3915/3915), 6.09 MiB | 31.84 MiB/s, done.
Resolving deltas: 100% (1828/1828), done.

現在のテーマを示す行をサイト構成ファイルに追加します。

ubuntu:~/quickstart$ echo "theme = 'ananke'" >> hugo.toml

クイックスタートのドキュメントに、サイトを表示するには、Hugoの開発サーバーを起動します。みたいなことが書かれてますが、実施してもコンテンツが無い為Page Not Foundになります。

ubuntu:~/quickstart$ hugo server -D
Watching for changes in /home/ubuntu/quickstart/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /home/ubuntu/quickstart/hugo.toml, /home/ubuntu/quickstart/themes/ananke/config/_default
Start building sites … 
（中略）
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) 
Press Ctrl+C to stop

実行結果にWeb Server is available at http://localhost:1313/とあり、実際にブラウザでhttp://localhost:1313/と入れて見に行くと、Page Not Foundが表示される。
正直Page Not Foundが表示されるので何か間違えたかとあたふたしましたが、コンテンツが無いので、この状態が正です。

コンテンツ追加

新しいページを追加。ここでやっと表示すべきコンテンツを準備していきます。

ubuntu:~/quickstart$ hugo new content content/posts/my-first-post.md
Content "/home/ubuntu/quickstart/content/posts/my-first-post.md" created
ubuntu:~/quickstart$ 

作成したmy-first-post.mdをエディタで開いて以下のように追記します。
試しに日本語も入れてみました。

+++
date = '2025-03-04T14:47:21Z'
draft = true
title = 'My First Post'
+++

## Introduction

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

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

## テスト
日本語は問題なく表示されてます。

まずはドラフトバージョンでビルドします。

ubuntu@public-instance-tokunaga-ubuntu2:~/quickstart$ hugo server -D
Watching for changes in /home/ubuntu/quickstart/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /home/ubuntu/quickstart/hugo.toml, /home/ubuntu/quickstart/themes/ananke/config/_default
Start building sites … 
(中略)
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) 
Press Ctrl+C to stop

ブラウザで確認してみます。無事に日本語も表示されてますね。

問題なければ、ここでdraft = falseに修正して保存しておきます。

サイトを構成する

hugo.tomlを開いて編集します。

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = 'ananke'    //この行を追加

サイトを公開する

hugo実行

ubuntu:~/quickstart$ hugo
Start building sites … 
hugo v0.145.0-666444f0a52132f9fec9f71cf25b441cc6a4f355+extended linux/amd64 BuildDate=2025-02-26T15:41:25Z VendorInfo=snap:0.145.0


                   | EN  
-------------------+-----
  Pages            | 10  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  1  
  Processed images |  0  
  Aliases          |  1  
  Cleaned          |  0  

Total in 104 ms

この時点で/public/index.htmlが作成され、ブラウザを見ると変わります。

コンテンツが上手く表示されないそんな時は？

ポイント① draftの値確認

• 例えば、タイトルは表示されているけど、中身が表示されない
  

• そもそもブラウザで以下のような表示が出た
  

恐らくdraftのステータスとhugoの開発サーバー起動オプションが間違っている可能性があります。

• draft = true なのにhugo serverで実行した
• draft = false なのにhugo server -Dで実行した

などなど、今一度コンテンツを確認してみてください。

ポイント② index.htmlが存在するか確認

私がクイックスタートを実施していく中で、正しくブラウザ表示していいはずなのになぜがコンテンツが表示されないことがありました。
その中で/public/index.htmlが存在しておらずhugoを実行することで、index.htmlが作成され正しく表示が出来ました。

参考になったQiita記事様