devkuma – Blog

Hugoブログ

kc@example.com (kc kim) — Tue, 29 Nov 2022 21:42:00 +0900

Docusaurusドキュメント生成ツール

kc@example.com (kc kim) — Tue, 29 Nov 2022 21:42:00 +0900

Hugoのページ要約時に韓国語の単語数を正しくカウントする(hasCJKLanguage, isCJKLanguage)

kc@example.com (kc kim) — Sun, 14 May 2023 16:06:00 +0900

Hugoのポスト一覧ページでは、記事の冒頭部分を特定の単語数(70語)だけ要約表示する。しかし、この単語カウントはデフォルトでは英語などの単語数を基準に計算されるため、韓国語などは正しくカウントされず、要約内容が長く表示されてしまう。

設定ファイルで設定する

韓国語の文字数を正しく計算し、短い要約を表示できるようにするには、設定ファイルで次のようにhasCJKLanguageをtrueに設定する。

config.tomlの場合

hasCJKLanguage = true

config.yamlの場合

hasCJKLanguage: true

これでHugo内部の.Summary、.WordCountが韓国語で正しく動作し、短い要約文が表示される。

各ページごとに設定する

各ページごとに設定したい場合は、次のようにFront matterでisCJKLanguageをtrueに設定する。

---
title: ポストタイトル
date: "2023-05-14"
isCJKLanguage: true
---

ポスト本文

設定ファイルではhasCJKLanguageを設定し、MarkdownファイルのFront matterではisCJKLanguageを設定する。

Hugoを始める

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Hugoソースディレクトリパス指定 - コマンドオプション(hugo server --source)

kc@example.com (kc kim) — Sat, 13 May 2023 02:25:00 +0900

ソースディレクトリパスを指定する

hugoコマンドを実行するとき、-s(--source)オプションを使ってソースディレクトリのパスを指定して起動できる。

例: ~/mysiteのソースコードを使ってHugoサーバーを起動

$ hugo server -s ~/mysite

例: ~/mysiteに新しい記事を作成

$ hugo new sample.md -s ~/mysite

コマンドエイリアスを設定する

上の例では-s ~/mysiteというオプションでソースディレクトリの指定を後ろに置いたが、前に指定してもHugoは動作する。

これを利用して次のようなコマンドエイリアス(alias)を設定しておくと、どのディレクトリからでもすぐにコマンドを実行できて便利である。 ~/.bash_profile

alias hugo-mysite=hugo -s ~/mysite

たとえば、次のように使用できる。

$ hugo-mysite new sample.md  # ポストを作成
$ hugo-mysite server         # Hugoサーバーを起動
$ hugo-mysite                # サイトをビルド(~/mysite/publicへ出力)

Hugoポストの作成方法

kc@example.com (kc kim) — Fri, 05 May 2023 23:34:00 +0900

新しいポストファイルを作成する

Hugoで公開するWebサイトのポストは、contentディレクトリにMarkdownファイルとして作成する(例: sample.md)。ポストファイルは空のテキストファイルから作成することもできるが、hugo newコマンドを使うと、ポスト形式ファイル(archetypes/default.md)を基にMarkdownファイルを自動生成できる。

ポストファイル(Markdownファイル)を作成する。

% hugo new sample.md
Content "/Users/user/my-site/content/sample.md" created

上記のように実行すると、contentディレクトリにsample.mdファイルが生成される。作成されたファイルの先頭には、次のようなFront matterと呼ばれるヘッダーが書かれている。このヘッダーはarchetypes/default.mdを基に自動生成されたものである。

content/sample.md

---
title: "Sample"
date: 2023-05-05T23:50:09+09:00
draft: true
---

その後、タイトル(title)を好きなように書き換え、Front matterヘッダーの後に記事本文を書いていけばよい。公開できる状態まで書けたら、ヘッダー部分のdraft: true行を削除する。

Archetypes

ここで基になるarchetypes/default.mdファイルを見てみよう。

archetypes/default.md

---
title: {{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---

titleフィールドにはhugo newコマンドで指定した名前が自動的に入り、dateフィールドには現在時刻が自動的に入る。このファイルの内容を基にポストファイルが作成されていることが分かる。

ポスト作成と同時にエディターで編集を始める

hugo newコマンドでポストファイルを作成するときに--editorオプションを指定すると、ポストファイルの生成と同時に指定したエディターでファイルを開ける。

例: 記事ファイルを作成してvimで開く

% hugo new sample.md --editor vim

初めて実行すると、次のようなエラーが出ることがある。

% hugo new sample.md --editor vi
Content "/Users/user/hugo-tutorial/my-site/content/sample.md" created
Editing "/Users/user/hugo-tutorial/my-site/content/sample.md" with "vi" ...
Error: access denied: "vi" is not whitelisted in policy "security.exec.allow"; the current security configuration is:

[security]
  enableInlineShortcodes = false

  [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$']
    osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM)$']

  [security.funcs]
    getenv = ['^HUGO_']

  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

表示されたメッセージのとおり、基本ポリシーをそのままコピーしてconfig.tomlに入れ、allow配列の項目に'^vim$'を追加する。

[security]
  enableInlineShortcodes = false

  [security.exec]
    allow = ['^dart-sass-embedded$', '^go$', '^npx$', '^postcss$', '^vim$']
    osEnv = ['(?i)^((HTTPS?|NO)_PROXY|PATH(EXT)?|APPDATA|TE?MP|TERM)$']

  [security.funcs]
    getenv = ['^HUGO_']

  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

その後もう一度試すと実行できるはずである。ただし、ポストファイルが先に作成されてからエディターを開くため、既にファイルがあるというメッセージが出る場合がある。

% hugo new sample.md --editor vim
Error: /Users/user/hugo-tutorial/my-site/content/sample.md already exists

その場合は既存のファイルを削除してから再実行すればよい。

Hugo概要 / インストール

kc@example.com (kc kim) — Wed, 19 Oct 2022 08:22:00 +0900

Static Site Generatorとは？

Static Site Generator(SSG、静的サイトジェネレーター)とは、静的ページベースのWebサイトを作成するツールであり、コンテンツやファイルを読み込んで適切にHTMLへ変換する技術である。

SSGの種類はこちらで確認できる。その中でも、GitHubと一緒によく使われる主なSSGは次のとおりである。

Jekyll
- Rubyベース
- 現在最も人気がある(GitHubで数が最も多い)
- 韓国語の参考資料が最も多い
- ビルドが比較的遅い
- Windowsは公式サポートされていない
Hexo
- Node.jsベース
- 中国語ドキュメントが多い
- 韓国語の参考資料が多い
Hugo
- Golangベース
- ビルドが速い
- ドキュメントがよく整備されている
- 韓国語の参考資料は多くない

Hugoとは？

Hugoは、JekyllやHexoなどと同じく、Webサイトを簡単に作成できるStatic site generatorの1つである。ブログエンジンの一種と言える。
ページはMarkdownで作成でき、多様なブログテーマが提供されているため、好みのテーマを選んで使用できる。

Hugoのインストール

以下のサイトからOSに合ったものをダウンロードしてインストールする。

https://github.com/gohugoio/hugo/releases

または、以下のサイトを参考にしてインストールする。

https://gohugo.io/getting-started/installing/

macOSでHomebrewを使ってインストール

macOS用パッケージマネージャーであるHomebrewを使うと、次の1行のコマンドで簡単にインストールできる。

Homebrewでインストールするコマンドは次のとおりである。

brew install hugo

実際にコマンドを実行してみる。

% brew install hugo
==> Downloading https://ghcr.io/v2/homebrew/core/hugo/manifests/0.104.3
######################################################################## 100.0%
==> Downloading https://ghcr.io/v2/homebrew/core/hugo/blobs/sha256:3b355290c70c54cf0637a9ed70342d289c9f022e4d085e18cb0e4651e3bbe21b
==> Downloading from https://pkg-containers.githubusercontent.com/ghcr1/blobs/sha256:3b355290c70c54cf0637a9ed70342d289c9f022e4d085e18cb0e4651e3bbe21b?se=2022-10-18T23%3A
######################################################################## 100.0%
==> Pouring hugo--0.104.3.arm64_monterey.bottle.tar.gz
==> Caveats
zsh completions have been installed to:
  /opt/homebrew/share/zsh/site-functions
==> Summary
🍺  /opt/homebrew/Cellar/hugo/0.104.3: 48 files, 55.8MB
==> Running `brew cleanup hugo`...
Disable this behaviour by setting HOMEBREW_NO_INSTALL_CLEANUP.
Hide these hints with HOMEBREW_NO_ENV_HINTS (see `man brew`).

すでにHugoをインストールしている状態でHugoを最新バージョンに更新するには、次のコマンドを実行する。

% brew upgrade hugo

インストール後にバージョンを確認できれば、正しくインストールされている。

% hugo version
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown

Windowsでのインストール

WindowsでHugoをインストールするには、HugoのReleasesページからzipアーカイブ(hugo_extendedx0.xxx.x_windows-amd64.zip)をダウンロードしてインストールする。
Sassなどの機能を使用する場合は、hugo_extendedで始まるファイルを使用する必要があるため注意が必要である。

配布されたhugo.exeを適切なディレクトリに置き、パスを通せばインストールは完了する。

Hugoで構成ファイル(config.yml)に設定された情報を参照する方法

kc@example.com (kc kim) — Sun, 14 May 2023 16:33:00 +0900

構成ファイルの基本

Hugoサイトの一般設定はルートディレクトリに置き、次の構成ファイルのいずれかを使用する。ファイルが複数ある場合は、最初に見つかった内容が選択される。

ファイル名	説明
`config.toml`	TOML形式で記述(デフォルト)
`config.yaml`	YAML形式で記述
`config.json`	JSON形式で記述

config.tomlの記述例

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "私のブログ"
themesDir = "../hugo_themes"
theme = "devkuma"

設定可能なパラメータやそれぞれのデフォルト値は、以下に一覧がある。

Configure Hugo | Hugo

設定値の参照

Hugoが定義したパラメータを参照する

構成ファイルで設定したパラメータは、テンプレートファイル内で.Site変数を使って参照できる。たとえば、config.tomlファイルで設定したtitleパラメータやbaseURLの値は次のように参照できる。

このサイトのタイトルは <b>{{ $.Site.Title }}</b> です。
このサイトの基本URLは <b>{{ $.Site.BaseURL }}</b> です。

パラメータ名の先頭は大文字になり、.Site.titleではなく.Site.Titleとなる。それぞれの設定値をどのプロパティ名で参照できるかは、下のSite変数一覧を見ると分かる。

パラメータが設定されているかどうかによって処理を分岐させるには、次のように記述する。

{{ with $.Site.GoogleAnalytics }}
  Google AnalyticsのTracking IDは <b>{{ . }}</b> です。
{{ else }}
  Google AnalyticsのTracking IDは設定されていません。
{{ end }}

上の例ではgoogleAnalyticsパラメータを使い、Google Analyticsの追跡IDが設定されているかを確認している。

ユーザー定義パラメータを参照する

構成ファイルでユーザー定義パラメータを設定するには、paramsセクションの下にパラメータを追加する。

config.toml

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "私のブログ"

[params]
  GitHubUser = "redfreek2c"
  Twitter = "kimkc"
  Subtitle = "技術共有"
  Description = "ここではサイト詳細情報を記録する"
  SidebarRecentLimit = 5
  ListOfFoo = ["foo1", "foo2"]

ユーザー定義パラメータは、テンプレートファイル内から$.Site.Params.名前の形式で参照できる。

次の例では、ユーザー定義パラメータ変数のDescription値を参照する。
layouts/partials/head.html

<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" />

ここでは、メインの最初のページ(ホームページ)では構成ファイルの設定($.Site.Params.Description)を参照し、それ以外のページでは各ページのFront matterに設定されたdescriptionの値を参照するようになっている。

Hugoポスト作成

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Hugoサーバー起動時のポート指定 - コマンドオプション(hugo server --port)

kc@example.com (kc kim) — Sat, 13 May 2023 02:32:00 +0900

Hugoサーバーをhugo serverコマンドで起動すると、基本的に1313番ポートを使用するWebサーバーが起動する。

しかし、複数のHugoサーバーを同時に起動しようとすると、それ以降のHugoサーバーには任意のポート番号が割り当てられる。Private portsである49152から65535までのポート番号が使用される。

ポート指定

任意のポート番号を使用するよう指定するには、次のように-p(--port)オプションを使う。

例: ポート番号51234でHugoサーバーを起動

$ hugo server -p 51234

複数のHugoサーバーを同時に起動する

複数のHugoサーバーを同時に起動する場合は、各サイトで使用するポート番号を決めておくとよい。

例: 3つのHugoサーバーを同時に起動

$ hugo server -p 50001 -s ~/mysite1
$ hugo server -p 50002 -s ~/mysite2
$ hugo server -p 50003 -s ~/mysite3

上記のように起動したWebサイトは、それぞれ次のアドレスでアクセスできる。

http://localhost:50001/
http://localhost:50002/
http://localhost:50003/

Hugoの下書きポスト作成方法 - Draft Page

kc@example.com (kc kim) — Sat, 06 May 2023 00:07:00 +0900

下書きポスト

Hugoの下書き(draft)機能は、未完成の記事ファイルを一時的に他の記事と同じ場所へ保存する機能である。ページのFront matter部分にdraft: trueと記入されている場合、そのページは下書きとして扱われる。

YAML形式の場合

---
draft: true
---

本文

TOML形式の場合

+++
draft = true
+++

本文

下書きとして作成されたポストは、基本的にHTMLファイルとして出力されない。下書きポストも出力したい場合は、hugoコマンドに-D(--buildDrafts)オプションを指定する。

下書きポストを出力

% hugo -D         # サイトを生成する場合
% hugo server -D  # サーバーを起動する場合

publicディレクトリに出力される下書きポストに注意

hugoコマンドはデフォルトでpublicディレクトリにHTMLファイルなどを出力するが、このときpublicディレクトリ内に既に存在する下書きポストは削除しない。

% hugo -D  # これでdraftポストを含めて生成される。
% hugo     # 次にdraftモードOFFで生成しても、既存の下書きポストは削除されない。

Webサイトを公開するときは、下書き記事が誤ってアップロードされないよう注意が必要である。ポストをアップロードする前にpublicディレクトリを削除し、その後hugoコマンドで再生成する方が安全である。

Linux / macOSの場合

% rm -Rf public && hugo

Windowsの場合

C:\> rmdir /s /q public & hugo

下書きポスト一覧の確認

コマンドラインで確認

コマンドラインでhugo list draftsを実行すると、contentディレクトリ内のポストのうち、下書きとしてチェックされている、つまりFront matterにdraft: trueが設定されている一覧を確認できる。

% hugo list drafts
content/draft.md
content/post/sample2.md

参考: hugo list drafts | Hugo

テンプレートで確認

テンプレートファイルで下書きポストへのリンクを列挙するには、まず次のように記述する。

layouts/index.html

<h2>Draft Pages</h2>
<ul>
  {{ range (where .Site.Pages ".Draft" true) }}
    <li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
  {{ end }}
</ul>

where .Site.Page ".Draft" trueとなっている部分は、下書きポストを抽出するための検索条件を指定している。
サイトのすべてのページ(.Site.Pages)から、ページ変数.Draftの値がtrueである(".Draft" true)ものを列挙するよう指定している。

そして、起動コマンドに-Dオプションを付けて実行する。

% hugo server -D

ポストが下書きかどうかを判別する

テンプレートファイルで、現在レンダリング中の記事が下書きかどうか、つまりFront matterにdraft: trueと書かれているかを確認するには、Page変数である.Draftを参照する。

layouts/_default/single.html

<h1>{{ .Title }}</h1>
{{ if .Draft }}
  <b>注意: このポストはまだ下書きです。</b>
{{ end }}

もちろん、起動時はコマンドに-Dオプションを付けて実行しなければ表示されない。

Hugoで新しいWebサイトを作成する

kc@example.com (kc kim) — Fri, 05 May 2023 18:17:00 +0900

サイトの骨格を生成する

まずHugoをインストールし、hugoコマンドを使用できる環境を用意する。そして、次のようにhugo new siteコマンドを使用すると、Webサイトの初期ファイル構成となるディレクトリの骨格を作成できる。

新しいWebサイト(my-site)を作成する

% hugo new site my-site
Congratulations! Your new Hugo site is created in /Users/user/hugo-tutorial/my-site.

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.

生成されるファイルは非常に簡単で、次のように2つのファイルといくつかのディレクトリだけである。

.
└── my-site
    ├── archetypes     : 新しいページを作成するときのテンプレートファイル
    │   └── default.md
    ├── config.toml    : サイト全体の設定ファイル
    ├── content        : コンテンツの保存場所。サイト内容となるMarkdown形式のファイルを置く。
    ├── data           : サイト生成時に利用するデータ
    ├── layouts        : レイアウトテンプレートの場所
    ├── public         : 生成されたHTML、CSS、画像などの配置場所
    ├── static         : 画像ファイルなど、サイト生成時にそのままコピーされるファイルを置く
    └── themes         : テーマディレクトリの場所。実際に使用するテーマはconfig.tomlで指定する。

この状態でサーバーを起動すると、“Page Not Found"と表示される。

サイトテーマのインストールと設定

Hugoで新しいWebサイトを生成した後は、外観を定義するためのテーマを1つ設定する。hugo new siteで作成したサイトにはテーマまでは生成されないため、サイトで公開されているテーマをダウンロードする必要がある。

ここではmainroadというテーマを適用してみる。

Hugoテーマは、themesディレクトリにテーマディレクトリを作成して保存すればよい。テーマごとにディレクトリを分けて保存するため、複数のテーマをあらかじめダウンロードしておくことができ、使用するテーマも簡単に変更できる。
また、テーマは主にGitHubで配布されているため、Gitがインストールされていれば、次のようにルートパスからgit cloneで簡単に適用できる。

% cd themes
% git clone https://github.com/vimux/mainroad

または、次のようにコマンドを一度に実行できる。

% git clone https://github.com/vimux/mainroad themes/mainroad

上記のコマンドでthemes/mainroadディレクトリが作成されたら、次にこのテーマを使用するようHugo設定ファイル(config.toml)へ次の内容を追加する。
config.toml

theme = "mainroad"

これでテーマ設定は完了である。

サイトのタイトルと言語設定

サイトの設定ファイルでは、テーマ設定以外にも、サイトタイトル(title)やサイト全体で使用する言語(languageCode)を設定する必要がある。

config.toml

baseURL = "http://devkuma.com/"
languageCode = "ko-kr"
title = "My New Hugo Site"
theme = "mainroad"

Info

ここで設定した値は、テンプレートファイルで`{{ .Site.Title }}`、`{{ .Site.BaseURL }}`、`{{ .Site.LanguageCode }}`のように参照できる。

ポスト作成

ここでは例としてポストを1つ作成してみる。次のようにhugo newコマンドを実行すると、contentディレクトリの下にポストファイル(Markdownファイル)が自動的に生成される。コマンドはプロジェクトの最上位ディレクトリで実行する。

$ hugo new post/sample.md

これでcontent/post/sample.mdファイルが作成されるので、次の形式に修正する。

content/post/sample.md

---
title: "ポストタイトル"
date: 2023-05-05T23:19:43+09:00
#draft: true
---

ポスト本文  
ポスト本文  
ポスト本文

ヘッダー部分のdraft: true行を削除またはコメントアウトしないと、ページが出力されないため、その行はなくす必要がある。

Hugo Webサーバーの起動

Webサイトのテーマ設定と記事作成が終わったら、hugo serverコマンドを実行してWebサーバーを起動する。

% hugo server
Start building sites …
hugo v0.104.3+extended darwin/arm64 BuildDate=unknown

                   | EN
-------------------+-----
  Pages            |  7
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  5
  Processed images |  0
  Aliases          |  3
  Sitemaps         |  1
  Cleaned          |  0

Built in 7 ms
Watching for changes in /Users/user/hugo-tutorial/my-site/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /Users/user/hugo-tutorial/my-site/config.toml
Environment: "development"
Serving pages from memory
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

Hugoサーバーの起動にかかる時間はわずか7msである。非常に速い。

Hugoサーバーが起動した状態でWebブラウザからhttp://localhost:1313/へアクセスすると、サイトの最初のページが表示される。

以後はhugo newコマンドを使ってポストを続けて作成していけばよい。Hugoサーバーはcontentディレクトリの変更を監視し、ポストが作成または修正されると自動的に再読み込みされるため、Hugoサーバーは一度起動すれば再起動しなくてもよい。

ポストのカスタマイズ方法はテーマごとに少しずつ異なるため、詳しい内容は各テーマのサイトを参照する必要がある。

HugoにGoogle Analyticsのトラッキングコードを挿入する(googleAnalytics)

kc@example.com (kc kim) — Sun, 14 May 2023 16:33:00 +0900

Google Analyticsを使用すると、Webサイトのアクセス情報を多角的に分析できる。ここでは、Hugoで作成したWebサイトにGoogle Analytics用コードを簡単に挿入する方法を説明する。

追跡IDを構成ファイルに設定する

まずGoogle Analyticsの管理画面で「プロパティを追加」を実行し、分析したいWebサイトのアドレスを追加する。Google Analyticsアカウントがない場合は、先にアカウントを作成する必要がある。このとき発行されるトラッキングID(G-AB1CD2EFGHのようなID)は、そのWebサイトへのアクセスを判別するための識別情報である。このIDはWebサイトごとに異なるものを使用するため、Hugo構成ファイルで設定するのがよい。

Hugoは構成ファイルのパラメータとして、あらかじめgoogleAnalyticsパラメータを提供している。次のようにGoogle Analyticsサイトで発行した追跡IDを設定する。
config.toml

baseURL = "https://www.devkuam.com/"
languageCode = "ko-kr"
title = "私のブログ"
theme = "devkuma"

googleAnalytics = "G-AB1CD2EFGH" # サンプルコード

上記のように設定すると、テンプレートファイルで.Site.GoogleAnalyticsからトラッキングIDを確認できる。

トラッキングコード(JS)を自動挿入するよう設定する

Google Analyticsを使用するには、各ページのhead要素の前に次のような追跡コードを含める必要がある。

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-AB1CD2EFGH"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'G-AB1CD2EFGH');
</script>

ここではHugoの部分テンプレートを使用し、上記のHTMLコードを各ページに含める。G-AB1CD2EFGHのようなトラッキングIDを指定する部分は、構成ファイルのgoogleAnalyticsパラメータで指定した値に置き換える。

layouts/partials/analytics.html

{{ if not .Site.IsServer }}
{{ with .Site.GoogleAnalytics }}
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', '{{ "{{" }} . }}');
</script>

{{ end }}
{{ end }}

上記テンプレートの1、2行目では、ローカルのHugoサーバーでテストしている場合やgoogleAnalyticsが設定されていない場合に、トラッキングコードを出力しないよう制御している。

作成した部分テンプレートは、次のようにテンプレートファイルから読み込む。ここでは基本テンプレート(baseof)から読み込んでいる。
layouts/_default/baseof.html

<!DOCTYPE html>
<html lang="ja">
<head>
  {{- partial "analytics" . -}}
  <meta charset="UTF-8">
  ...省略...
</head>
<body>
  ...省略...
</body>
</html>

これで、すべてのページにGoogle Analyticsのトラッキングコードが含まれる。

付録: Hugo内蔵テンプレート

実はHugoは、Google Analyticsの追跡コードを含むInternal Templateを内蔵テンプレートとして提供している。

任意のテンプレートファイル内で次のように書くだけで、簡単に追跡コードを挿入できる。

{{ template "_internal/google_analytics.html" . }}  <!-- 同期版 -->
{{ template "_internal/google_analytics_async.html" . }}  <!-- 非同期版 -->

ただし、内蔵テンプレートはローカルサーバー動作時のコード出力抑制には対応しておらず、Googleの変更にも柔軟に対応できない可能性があるため、できれば部分テンプレートを作成しておく方がよい。

Hugoコマンド

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Hugoサーバーでページ変更内容が反映されない場合(hugo server --ignoreCache)

kc@example.com (kc kim) — Sun, 14 May 2023 14:30:00 +0900

キャッシュ無視オプション

Hugoサーバーを起動してページが更新されても、Webブラウザを再読み込みしても変更内容が反映されないことがある。特にlayoutsやpartialsなど、共有して使用する部分で起こりやすい。

ページのビルドには成功したのに変更内容が反映されない場合は、Hugoサーバーのキャッシュを疑ってみるとよい。hugo serverコマンドを実行するときに--ignoreCacheオプションを使用すると、キャッシュを使用せずにレンダリングされる。

$ hugo server --ignoreCache

Hugoテーマ設定方法 - Themes

kc@example.com (kc kim) — Tue, 09 May 2023 00:40:00 +0900

テーマのダウンロード

HugoでWebサイトを生成するときは、見た目の基本テーマを設定する必要がある。テーマを設定せずにhugoコマンドでWebサイトを出力しても、真っ白なページが表示される。テーマは自分で作成することもできるが、Hugo Themesというページに他の人が既に作成したテーマが公開されているため、まずはここからダウンロードして使用するとよい。使い方はテーマごとに少しずつ異なるため、詳しい内容は各テーマの説明(README.md)を読むことを勧める。

テーマZIPファイルをダウンロードする方法

たとえば、下の“Beautiful Hugo”というテーマが気に入った場合は、下のDownloadボタンを押す。

一般的にはGitHubサイトへ移動するため、“Code"を押し、“Download zip"ボタンを押してテーマをダウンロードする。

ダウンロードしたテーマはプロジェクトのthemesディレクトリに入れる。ここではthemes/beautifulhugoディレクトリに入れればよい。

テーマをGitから取得する方法

テーマはGitHub上で管理されているため、Gitコマンドを使用できる環境であれば、次のようにgit cloneで取得するのが簡単である。もちろん、まずリポジトリのURLを知っている必要がある。URLはGitHubでCodeボタンを押して表示されるURLをコピーすればよい。

$ git clone https://github.com/halogenica/beautifulhugo.git beautifulhugo

もし自分のサイトをGitで管理している場合は、次のようにテーマをGitサブモジュールとして取り込むのがよい。Gitサブモジュールのコマンド(git submodule)は少し難しいが、テーマをサブモジュールとして管理すると、テーマ側の更新を適切に反映できる。

テーマをサブモジュールとして取得する

$ git submodule add https://github.com/halogenica/beautifulhugo.git beautifulhugo

テーマの更新を取得するとき

$ git submodule update --remote --recursive

必要な場合のテーマ別設定

テーマによっては外部コンポーネントに依存しており、初期設定が必要なものもある。テーマで次のように関連モジュールをインストールするよう求められた場合は、そのまま次のコマンドを実行しておく。

$ npm install
$ npm run build

参考までに、npmはNode.js用のパッケージマネージャーであり、Node.jsをインストールすると一緒にインストールされる。

使用するテーマを指定する

テーマはthemesディレクトリに複数ダウンロードできる。その中で現在使用したいテーマは、Hugo設定ファイルで次のように設定する。

config.toml

theme = "beautifulhugo"

テーマを設定した後、hugoコマンドでWebサイトを生成してみる。設定したテーマを基に、アップロード用のHTML、CSS、JSなどのファイルがpublicディレクトリに出力される。

$ hugo

hugo serverコマンドは、Webサーバーを起動するときにconfig.tomlで設定したテーマを使用する。

hugoコマンドを実行するときに、-tオプションで使用するテーマを指定することもできる。

$ hugo -t theme_name         // サイトを出力する場合
$ hugo server -t theme_name  // Webサーバーを起動する場合

Hugo設定

kc@example.com (kc kim) — Sun, 14 May 2023 15:36:00 +0900

Hugoで新しい自分のテーマを作る - new theme

kc@example.com (kc kim) — Tue, 09 May 2023 00:40:00 +0900

自分のテーマを新しく作る

Hugoには既に公開されているテンプレートが多くあるが、自分で思いどおりにデザインしてテーマを作成することもできる。テーマを作成するには、まず次のコマンドで基本形式を作る。

$ hugo new theme {テーマ名}

たとえば、次のように実行するとthemes/my-themeディレクトリが作成される。

$ hugo new theme my-theme

生成されるファイルは次のようになっており、ディレクトリ構成は作られるが、ファイルの内容はほとんど空である。これらのファイルを基にテンプレートを作成する。

新しく作成されたテーマの形式

themes/my-theme
├── LICENSE   (MITライセンス)
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── head.html
│       └── header.html
├── static
│   ├── css
│   └── js
└── theme.toml (基本設定ファイル)

最初のページレイアウト(layouts/index.html)を作る

テーマディレクトリ内のlayouts/index.htmlファイルは、サイトの最初のページに対するテンプレートファイルである。1つのHTMLファイルだけで構成されたサイト(SPA: Single Page Application)を作成する場合、このファイルだけを作成すればよい。初期状態では何も記述されていないため、まずは起動時にサイト名だけを表示するよう修正してみる。

themes/my-theme/layouts/index.html

<h1>{{ .Site.Title }}</h1>

上記のように、サイト情報を保持する.Site変数のTitleフィールド値を出力できる。ここにはサイトの設定ファイル(config.toml)のtitleに設定した文字列が表示される。

ここまで作成したら、このテーマを使用してサイトを確認する。hugoコマンドと一緒に使用するテーマを指定するには、-t {テーマ名}オプションを使う。

$ hugo server -t my-theme

上記のようにHugoサーバーを起動した後、http://localhost:1313/ にアクセスして表示を確認できる。

図: 自分のテーマを使用した最初のページ

最初のページにすべてのページ一覧を表示する

最初のページのテンプレート(layouts/index.html)内で.Data.Pages変数を参照すると、すべてのページ情報(Page変数)を取得できる。この情報をrangeでループ処理すると、すべてのページへのリンクを出力できる。

themes/my-theme/layouts/index.html

<h1>{{ .Site.Title }}</h1>
<ul>
  {{ range .Data.Pages }}
    <li><a href="{{ .RelPermalink }}">{{ .Title }}</a> ({{ .Date.Format "2006-01-02" }})</li>
  {{ end }}
</ul>

各ページ用のレイアウトを作る(layouts/_default/single.html)

リンクされた各ページはlayouts/_default/single.htmlテンプレートファイルを基に生成されるため、このファイルをあらかじめ作成しておく必要がある。このテンプレート内ではPage変数のフィールドを参照できる。たとえば、.Titleでページタイトル、.Contentでページ本文を参照できる。

themes/my-theme/layouts/_default/single.html

<h1>{{ .Title }}</h1>

{{ .Content }}

各ページの内容は、content/ディレクトリ内に次のような形で作成しておく。

content/page1.md

---
title: "Page1 Title"
date: "2017-09-10"
---

Page1 Content

上記のようにレイアウトファイルとコンテンツを作成しておくと、各ページの内容が次のように表示される。

図: 単一ページテンプレートで出力

以後は、同じようにlayoutsディレクトリ内のテンプレートコードを作成していけば、自分のテーマが完成する。Markdownファイルで使用できるショートコード(short codes)も、独自のテーマ部品(layouts/shortcodes)として提供できる。

複数のHugoサイトで同じテーマディレクトリを設定する(themesDir)

kc@example.com (kc kim) — Sun, 14 May 2023 14:23:00 +0900

複数のHugoプロジェクトで同じテーマを参照させる方法は次のとおりである。

GitHubなどにテーマ用リポジトリを作成し、そのリポジトリを複数のHugoプロジェクトへcloneする。
各Hugoプロジェクトのthemesディレクトリを、共通テーマディレクトリへのシンボリックリンクに置き換える。
設定ファイル(config.toml)で共通テーマディレクトリを参照するよう設定する。

1つ目の方法が最も一般的だが、Gitで各サイトのテーマを同じように適用する場合、開発段階では少し面倒なことがある。そのような場合におすすめなのが2つ目と3つ目の方法である。

シンボリックリンクで共通テーマディレクトリを指定する

LinuxやmacOSなど、シンボリックリンクを作成できるOSでは、共通テーマディレクトリをシンボリックリンクで参照するのが簡単である。たとえば、次のように共通で使用するテーマディレクトリ(hugo_themes)と、それを参照する3つのHugoプロジェクト(site1、site2、site3)があるとする。

.
├── hugo_themes (共通テーマディレクトリ)
│   └── mytheme
│       ├── archetypes
│       ├── layouts
│       ├── static
│       └── ...
├── site1  (Hugoサイト1)
├── site2  (Hugoサイト2)
└── site3  (Hugoサイト3)

各Hugoプロジェクトのthemesディレクトリをhugo_themesへのシンボリックリンクに置き換えると、すべてのサイトで同じテーマディレクトリを参照できる。

$ cd site1
$ rmdir themes
$ ln -s ../hugo_themes themes

使用するテーマ名の設定は必ず必要なので、各Hugoプロジェクトの設定ファイル(config.toml)にテーマ名を設定する。 site1/config.toml

theme = "mytheme"

設定ファイルで共通テーマディレクトリを設定する

Hugo設定ファイル(config.toml)に共通テーマディレクトリを設定する方法もある。テーマディレクトリの設定はthemesDirという変数で行い、このディレクトリパスにはHugoプロジェクトより上位のディレクトリパスを設定できる。
config.toml

themesDir = "../hugo_themes"
theme = "mytheme"

たとえば、各Hugoプロジェクトの設定ファイルで上記のように設定すると、上位ディレクトリにある共通テーマディレクトリ(hugo_themes/mytheme/)を使用できる。

設定ファイルを使用せず、Hugoコマンドオプション--themesDirでテーマディレクトリを指定することもできる。

$ hugo server --themesDir ~/gitwork/hugo_themes

設定ファイルのthemesDir変数とコマンドライン引数--themesDirの両方が指定された場合、コマンドライン引数が優先される。

Hugoで使用していないテンプレートやShortcodeを確認する(hugo --printUnusedTemplates)

kc@example.com (kc kim) — Sun, 14 May 2023 15:32:00 +0900

Hugoサイトをビルドするときに使用していないテンプレートを検索するには、次のように--printUnusedTemplatesオプションを使用する。

% hugo --printUnusedTemplates
Start building sites …
hugo v0.111.3+extended darwin/arm64 BuildDate=unknown

...省略...

WARN 2023/05/14 15:25:46 Template _default/list.rss.xml is unused, source file /Users/user/...省略.../mysite/layouts/_default/list.rss.xml
WARN 2023/05/14 15:25:46 Template _default/single.html is unused, source file /Users/user/...省略.../mysite/themes/docsy/layouts/_default/single.html
WARN 2023/05/14 15:25:46 Template blog/baseof.html is unused, source file /Users/user/...省略.../mysite/docsy/layouts/blog/baseof.html

...省略...

WARN 2023/05/14 15:25:46 Template swagger/single.html is unused, source file /Users/user/user/...省略.../mysite/themes/mytheme/layouts/swagger/single.html
Total in 3146 ms

上記の例では、複数のテンプレートやショートコードが使用されていないことが分かる。

複数のHugoサーバーを一度に起動および終了する方法

kc@example.com (kc kim) — Sun, 14 May 2023 14:52:00 +0900

Hugoサーバーの複数起動について

Hugoで複数のサイトを実行する必要がある場合に、1つのコマンドプロンプトから同時にサーバーを起動する方法について説明する。

ここでは、次のようにホームディレクトリ配下に複数のHugoプロジェクトがあると仮定する。

~/website/site1
~/website/site2
~/website/site3

各Hugoプロジェクトに対してHugoサーバーを起動するには、次のようにポート番号を変えて複数のHugoサーバーを起動できる。

$ hugo server -p 50001 -s ~/website/site1
$ hugo server -p 50002 -s ~/website/site2
$ hugo server -p 50003 -s ~/website/site3

しかし、上で説明したように1つのサーバープロセスが1つのコマンドプロンプトを占有するため、複数のHugoサーバーを起動するときは複数のコマンドプロンプトを開いておく必要がある。

1つのプロンプトで複数のHugoサーバーを起動する

Windowsの場合

Windowsのstartコマンドを使用すると、Hugoコマンドをバックグラウンドで実行できるため、追加のコマンドプロンプトを開かなくても複数のHugoサーバーを起動できる。

たとえば、次のバッチファイルはバックグラウンドで3つのHugoサーバーを起動する。
start-servers.bat

@echo off
start /b hugo server -p 50001 -s C:/website/site1
start /b hugo server -p 50002 -s C:/website/site2
start /b hugo server -p 50003 -s C:/website/site3
title Hugo Servers

最後の行のtitle Hugo Serversというコマンドで、コマンドプロンプトのウィンドウタイトルを"Hugo Servers"に変更する。ウィンドウタイトルを変更しておくと、タスクバーを見ただけで何のためのウィンドウか判別しやすくなるためおすすめである。

バックグラウンドで実行されているHugoサーバーをまとめて終了するには、taskkillコマンドを使用してhugo.exeプロセスをすべて終了する。

stop-servers.bat

@echo off
taskkill /f /im hugo.exe

Linux、macOSの場合

Linux、macOSの場合は、次のように最後に&を付けてHugoコマンドを実行すると、簡単に複数のサーバーをバックグラウンドで起動できる。
start-servers.sh

hugo server -p 50001 -s ~/website/site1 &
hugo server -p 50002 -s ~/website/site2 &
hugo server -p 50003 -s ~/website/site3 &

Hugoサーバープロセスをまとめて終了するには、killallコマンドで簡単に終了できる。
stop-servers.sh

killall hugo

またはシェルスクリプトではなく、関数やエイリアスとして定義して使用すると速い。
~/.bash_profile

function hugo-start {
    hugo server -p 50001 -s ~/website/site1 &
    hugo server -p 50002 -s ~/website/site2 &
    hugo server -p 50003 -s ~/website/site3 &
}

function hugo-stop {
    killall hugo
}