静的サイトジェネータ Hugo（ヒューゴ）についてまとめています。

詳細な日本語説明サイトもできているため、簡単な説明に留めています。
詳しい説明は必要に応じて検索してみて下さい。

例えば 🎈 Let’s Encrypt の Web サイトは Hugo が採用されています。

を実行すると Web サーバが起動します。
Web ブラウザより http://localhost:1313/ を参照すると、完成された状態で参照できます。
サーバを起動したままファイルを編集します。
ファイル保存で Web ブラウザの表示に即反映されます。
主に次のところを追加・編集する事になります。

config.toml - サイト全般の設定
content/ 内 - ページ・ブログ記事（通常は .md ファイル）
static/ 内 - 画像・JavaScript・CSS など（この中はそのままコピーされます）

作業完了時は Ctrl+C でサーバ動作を停止できます。

完成したところで、cd サイト名 へ移動し
（ config.toml と複数のフォルダ（ディレクトリ）があるところ）
次のコマンドでビルドします。

hugo

この時 Minify が可能です。

public/ 内に index.html などが生成されます。

あとは生成されたファイルをアップロードします。
PHP などは使われていないため、多くの Web サーバで公開できます。
FTP でアップロードしてもいいですが、
Hugo 採用に合わせてサーバを変更すると公開も快適です。

Category: hosting and deployment | Hugo Documents
CLI によるアップロード・公開

なお、記事のタイトルを変更した場合などは使用しないファイルが発生しますが、
Hugo は public/ 内のファイルを削除しません。手動で削除する必要があります。

'hugo clean' #2389 | GitHub gohugoio/hugo issues

フォルダ・ディレクトリ構成

hugo new site フォルダ名 で生成したフォルダ（ディレクトリ）内は
次の内容で構成されています。これはテーマ共通です。

archetypes/

デフォルトでは default.md しか入っていないでしょう。
hugo new 記事ファイル.md の時に参照されるテンプレートファイルです。
多くのテーマではここに追加しませんが、独自のファイルを追加できます。

content/

ブログでいう記事ファイルを入れます。通常 Makrdown .md ファイルです。
現在はフォルダを作成して、関連する画像ファイルなどを一緒に入れる事もできます。

通常 content/ 直下は public/ 直下で生成されますが、
config.toml に [permalinks] を加えた場合は、生成が変化します。

[permalinks]
  post = "/:year/:month/:slug/"

この場合 content/post/ 内のファイルは public/ 内で
2021/02/記事名/ で生成されます。

_index.md が index.html 相当になります。
ブログではない Web ページ用途でトップページの生成で必要になりますが、
一覧表示に対応しているテーマでも前後にテキストを追加できる場合があります。

なお、Hugo では伝統的にブログ関連は content/post/ を採用するテーマが多いです。

data/

データファイルをここに入れる事で、ビルドで処理させる事ができます。
一部のテーマで使用されている事がありますが、通常はあまり触れる事がないでしょう。

layouts/

変更したテンプレートファイルを入れます。
オリジナルは themes/テーマ名/layouts/ 内にあり、
layouts/ に入れたファイルはこのテーマにあるファイルを上書き適用します。

layouts/ 直下が public/ 直下です。
通常はそのまま構成するファイル名になっていて、
index.html や 404.html などがあります。
404.html は Not Found 表示です。

partials/ は細かいパーツ毎に置いてあります。
テーマによって構成が異なりますが、おおよそ次になります。

head.html - <head> 関連
header.html - ページ上部
footer.html - ページ下部

contents/post/ など、 contents/ 下部にフォルダがある場合、
該当するフォルダ名が layouts/ にない場合は _default/ を参照します。
layouts/ 内に post/ あると、そのフォルダが有線適用されます。
構成ファイルは主に次のファイルです。

list.html - 記事一覧（フォルダ内）
sinple.html - 記事ページ

その他、テーマにより shortcodes/ があり、
特定の出力を容易に記載する方法があります。

テーマを使用しない場合はここにテンプレートファイルを構築する事になります。

public/

hugo で生成された HTML ファイルと画像ファイルなどがここに入ります。
これをサーバへ公開します。
出力先を public/ から変更する場合は config.toml に publicDir で指定します。

resources/

hugo 実行ファイルが一時ファイル生成に使用します。触れる事はありません。

static/

ここに入れたファイルはそのまま public/ へ入ります。
robots.txt や favicon.ico apple-touch-icon.png 、
JavaScript や CSS ファイルも通常はこちらです。

画像ファイルはこちらに入れての使用も可能です。

なお、Hugo はデフォルトでサイトマップ sitemap.xml を生成するので、
これは手動で生成する必要はありません。

themes/

通常この仮想に git clone URL または git submodile add URL として
テーマファイルを入れます。
完全に生成する場合はこれを使用しません。
themes/ の中は通常ファイル編集しないで下さい。 変更する場合はコピーします。
よく使うのは themes/テーマ名/layouts/ 内から layouts/ 内へのコピーでしょう。

exampleSite があるテーマが多いです。
生成したフォルダの構成に合わせてコピーすると、デモページを再現できます。

config.toml

設定ファイルです。サイト共通の設定はここに入れます。テーマの指定なども行います。
テーマによって config.yaml もあります。

その他

それ以外は Hugo は通常使用しません。
必要な場合は関連ファイル・フォルダを生成できますが、
当然 GitHub などでプロジェクト公開する場合はこれらも公開されてしまうので、
考慮が必要です。

ファイル構成

テーマによってファイル構成は変わってきます。
ここでは比較的テーマで共通している内容で最低限触れるところを説明します。

config.toml

config.yaml で公開しているテーマもあります。

baseurl = "https://example.net.eu.org/"
publicDir = "public"
title = "Hugo のつかいかた。"
theme = "whiteplain"
languageCode = "ja"
defaultContentLanguage = "ja"
googleAnalytics = "UA-00000000-0"
disqusShortname = "name"
disableKinds = ["taxonomy","taxonomyTerm"]

baseurl 公開 URL（末尾 / の有無は exampleSite の記載に合わせて）
baseurl にはディレクトリも含める事も可能です。
basedir = "https://example.org/dir/" の場合
hugo server は http://localhost:1313/dir/ です。
publicDir index.html などの出力先。通常は存在せず public/ へ出力
title サイト名
theme 使用するテーマ名（themes/テーマ名/ で参照）
languagecode 日本語の場合は ja（html タグの lang で使用される場合あり）
※ ja-JP も使えるが、ja は日本語言語ファイルを適用するテーマが存在する
defaultContentLanguage 日本語の場合は ja
googleAnalytics Google アナリティクストラッキング ID
（テーマによっては独自実装の場合あり）
Google アナリティクス 4（GA4）の測定 ID は非対応の可能性があります。
disqusShortname Disqus（コメントシステム）のショートネーム
disableKinds カテゴリ・タグを使用しない場合は ["taxonomy","taxonomyTerm"]
※ 指定しない場合、何もないカテゴリ・タグページが RSS・サイトマップに入ってしまう
RSS・サイトマップも使用しない場合は ["RSS","sitemap","taxonomy","taxonomyTerm"]

更にテーマ独自の設定として [params] の項目が続きます。

なお、toml では、""" で囲む事で複数行で記載ができます。
" の前に \ を付ける必要もありません。HTML や Markdown が使える項目に便利です。

copyright = """
Copyright &copy; 2021 
<a href="https://balloon.asia/" target="_blank">ふうせん🎈 FU-SEN</a>
"""

content/ 内

hugo new ページ名.md で archetypes/default.md を元に content/ページ名.md で生成されます。
すでに .md ファイルがある場合、コピーしても構いません。
ブログは通常 content/post/ 内です。hugo new post/ページ名.md となります。
index.html に該当するのは _index.md となります。（頭の _ に注意）
ここでは yaml での記載です。--- を +++ にすると toml になります。

---
title: "Hugo のつかいかた。"
slug: "Hugoのつかいかた"
date: 2021-05-08T16:20:00+09:00
categories:
- web
- ブログ
tags:
- Hugo
- CSS
- Blog
- ブログ
keywords:
- Hugo
- CSS
description: "Hugo についての紹介。"
weight: 10
draft: false
---

title ページ名・記事のタイトル
slug URL 表示ディレクトリ名（ファイル名）ページ URL を変更したいのですが……
date 日付。現在より未来だと非公開。末尾 +09:00 で日本標準時
category カテゴリ。二つ以上の場合、二つ目以降はサブカテゴリ扱い
tags タブ。複数指定可能
keyword キーワード。テーマにより meta タグに使用される
description テーマにより meta タグに使用される
weight 並び順。メニューなどで使用。Web サイトでは必須
draft true の時は下書き。hugo server -D で参照できる

その他、ページ・記事別の画像が項目にある場合が多いです。ヘッダ画像と OGP に使われます。

すべて記載する必要はありません。多くは省略可能です。
最小限は title・date、日付表示もなければ title のみになります。
draft を使うように記載されている事が多いですが、
サイト運営者は draft を使っていません。
なければ draft: false に同じで、-D なしでも表示・公開の対象です。

---
title: "Hugo のつかいかた。"
date: 2021-05-08T16:20:00+09:00
---

# Hugo のつかいかた。

静的サイトジェネータ **Hugo** （ヒューゴ）についてまとめています。

本文は Markdown で記載していきます。
~~取り消し線~~ など GitHub Flavored Markdown（GFM）も有効です。

🎈 Markdown | ふうせん🎈 FU-SEN

メニュー

Hugo でメニュー機能が存在しているため、多くのテーマはそれを採用しています。
contect/ 内の .md ファイルで記載する方法と、config.toml に記載する方法があります。

content/ の .md ファイルをメニューに表示する場合は次です。
ここでは date などを省略しています。

---
title: "Hugo のつかいかた。"
type: "top"
menu: "main"
weight: 1
---

config.toml に記載する場合は次です。
この場合 name で自由にメニューの表示名を付けられます。
また url は /～によるサイト内、https:// による外部も指定できます。

[[menu.main]]
  name = "Hugo のつかいかた。"
  weight = 1
  identifier = "top"
  url = "https://example.net.eu.org/"

テーマによっては独自の異なる方法で実装している場合がある事にご注意下さい。

Menus | Hugo Documents

Minify

HTML などの余計な空白・改行をなくして表示の高速化ができます。
ただし、生成時間がかかるので、ページ数の多いブログなどは特に注意して下さい。

hugo --minify

config.toml に追加するように対応もしているようですが、
サイト運営者が試した感じでは動作していないようです。

Cloudflare を使用している場合、Cloudflare 側で Minify を実現できます。
改行は残されるため、ソースが見やすい Minify という感じです。
（ドメイン選択後、Speed - Optimization - Auto Minify）

Web サービスによる対応

Cloudflare Pages

Cloudflare Pages
🎈 Cloudflare Pages | ふうせん🎈 FU-SEN

2020年12月よりベータ版公開され、2021年5月より正式公開となった、
Cloudflare の新サービスです。
GitHub 連携のため、GitHub アカウントが必要です。
リポジトリは公開必須ではなく、プライベートリポジトリでも使用できます。

ビルドプリセットに Hugo が存在し、
容易に Hugo でビルドした Web サイトを公開できます。

デフォルトは Hugo 0.54 と古く、そのままではテーマが非対応の場合があります。
環境変数 HUGO_VERSION でバージョンを指定できるので、
最新バージョンまたは使用しているバージョンに設定してからビルドして下さい。

Vercel

▲ Vercel
🎈 Vercel | ふうせん🎈 FU-SEN

Vercel は Hugo のビルドに対応しています。

▲ Create a Hugo Website and Deploy It with Vercel | Vercel Blog

Hugo のディレクトリ構成から vercel --prod
または GitHub・GitLab・Bitbucket への git push で
Hugo のビルドを行い、公開します。
通常 Vercel ははじめてビルドする段階で Hugo を仕様している事を自動認識し、
適切なビルドを行うため、細かい設定を行う必要はありません。

Hugo のバージョンで仕様が異なる場合があるため、
使用している Hugo のバージョンを指定する事をおすすめします。
vercel.json で環境変数 HUGO_VERSION を設定します。次は 0.101.0 にしています。

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.101.0"
    }
  }
}

Q&A

正式表記は Hugo と HUGO どちらですか？

HUGO はロゴタイプとして使用されています。ロゴと公式サイト（gohugo.io）の左上のみです。
一方 Hugo は全般的によく表記されています。
したがって、Hugo が公式的な一般表記 と判断できます。

デプロイがとてもはやいと聞いたのですが？

現在見ている 🎈 balloon.asia は
2022年5月現在、Markdown などのページが 210 ページを超えていますが、
初期の Core i5 マシンでも数秒でビルドが完了します。
（しかも運営者はいつも音楽や動画を再生しながら作業しています）
Hugo に関係ない、サーバにアップロードするデプロイの方が時間を要します。
こんなにビルド時間がはやい静的サイトジェネータを運営者は他に知りません。

最新版を素早く知る方法はありますか？

GitHub リポジトリに入ります。GitHub はログインしておきます。

GitHub - gohugoio / hugo

右上 Notifications 部分を Release only に変更して下さい。
これにより、ログインしている GitHub アカウントのメールアドレスに
最新バージョンが公開されたタイミングで通知が届くようになります。

画像ファイルはどこに入れれば良いのですか？

static/ 内に入れるのが一つの方法です。
この場合は public/ 内にそのまま入ります。

また、 contents/ 内に記事と一緒に画像を入れる事もできます。
例えば contents/名前/ でディレクトリを生成し、
（名前は記事名など、名前.md の代わりにディレクトリ名を作成）
_index.md の記事と一緒に画像をまとめます。
これにより記事と画像が同じディレクトリにあるので、
画像の指定はファイル名のみにできます。

config の permalinks より年・月ディレクトリを生成している場合、
それに合わせて画像ファイルを置くのも手です。

コメントは付けられますか？

Comments | Hugo Documents

Hugo は config.toml の設定項目として disqusShortname を用意していて、
Disqus の追加に対応しています。そのため、多くのテーマは Disqus に対応しています。

Disqus

スマートフォン対応にできますか？

Hugo のテーマはほぼ全てレスポンシブ対応です。
スマートフォンで表示した時は最適化されるように作られてあります。
パソコンでウインドウの横幅を縮めてみると分かります。
Googlebot はモバイル対応と認識します。安心してテーマを適用して下さい。

一部の表示がおかしいです

0.57 より一覧表示の仕様が変わっています。
テーマが対応していない場合、表示がおかしくなります。

🎈 Hugo 0.57.0 更新後、Posts のみが表示されるようになった場合。| ふうせん🎈 FU-SEN

WARN 表示が出ています

0.55 よりテーマで古い表記のままになっている場合に発生します。

ダウンロードしたテーマで発生している場合は、
そのテーマの GitHub リポジトリへ issue して修正を依頼して下さい。

修正箇所は layouts/ 内のテンプレートになります。ここでは具体的には触れません。

.md ファイルに HTML 入れても認識しません

0.60 より config.toml に次を追加して HTML を記載できます。
これを付けないと HTML タグをコメントに置き換えて無効にします。

[markup.goldmark.renderer]
  unsafe = true

HTML ファイルに出力されないコメントはどのようにすれば良いですか？

テンプレートファイルでは単に HTML のコメント  が有効です。
HTML ではこれが省略されます。

cotnent/ に入れる .md ファイルでは、
コメントが変換されるか（デフォルト）、そのまま出力されます。

ショートコードで対処する手段が使えます。
layouts/shortcodes/ 内に任意の コード名.html で
次の中身を入れたファイルを生成します。

{{ if .Inner }}{{ end }}

comment.html で作成した場合、.md ファイル内は次のコメント記載が可能になります。

{{< comment コメント >}}{{< /comment >}}

上の方法でエラーになる場合は "コメント" と "～" で囲って下さい。

{{< comment >}}コメント{{< /comment >}}

上の方法は複数行記載できます。

この方法は Hugo 公式サイトで todo.html として実際に使われています。

layouts/shortcodes/todo.html | GitHub gohugoio/hugoDocs

強制改行したい場合は？

Hugo の .md ファイル内では、改行を入れても改行されません。空白になります。

改行したい場合は、行末・改行直前で \（半角＼または半角￥）を入れるか、
半角スペースを 2 文字入れます。

HTML を有効にしている場合は <br> も使えます。

TOC（Table Of Content）で認識されない見出しを作るには？

HTML の <h1>～<h6> タグは TOC で認識されません。

ページ URL を変更したいのですが……

config.toml で permalinks を使用します。
ない場合は追加、ある場合は変更します。
通常ブログで使われる content/post/ 内を Web サイトのように使う目的で
https://サイト/タイトル/ にしたい場合は次のようにします。

[permalinks]
  post = "/:title/"

日本語も有効な URL として正しく動作しますが、
サーバによって不具合がある場合があります。
また FTP でアップロードする場合ファイル名を変換しないで下さい。

/:year/:month/:slug/ や /:year/:filename/ という指定もできます。
:slug は content/ 内の項目として slug を入れる事で、
これがディレクトリ名（ファイル名）になります。
ない場合は title が扱われますので、通常は title、
必要に応じて slug 付加という場合でも :slug が使えます。

URL Management | Hugo Documents

通常の Web サイトとブログを合わせたサイトを構築できますか？

できます。実際参照している 🎈 balloon.asia がこの構成です。
config.toml の permalinks を次に設定しています。

[permalinks]
  post = "/:year/:month/:slug/"
  content = "/:slug/"

🎈 post/ がブログ、 🎈 content/ が複合コンテンツです。
/contents/_index.md は /layouts/index.html で記事ページに近いものにして、
通常のテキストを記載しています。

更にヒントとして /layouts/_default は post ・ content 共通ですが、
/layouts/post で生成すると post 、
/layouts/content で生成すると content 内での一覧・記事ページになります。

この辺ができるようになると、Hugo で本格的なサイト構築ができるでしょう。
Hugo の扱いに慣れてきたらチャレンジしてみて下さい。

独自の CSS を含めたい場合はどのようにすれば良いですか？

テーマによって異なります。主に次のいずれかです。

config.toml で customCSS などの項目がある場合、
.css 名を記載し、static 内に生成します。
themes/static/css/ 内に空の custom.css などがある場合、
これを static/css/ 内に入れて追加します。
これらが見つからない場合は themes/テーマ名/layouts/partials/ 内を確認し、
head タグ内を記載している html ファイルを見つけ出して layouts/partials/ 内に入れ、
CSS を追加するよう追記します。head.html に追記する場合が多いです。
themes/テーマ名/layouts/partials/ 内にない場合は
themes/テーマ名/layouts/_defaults/baseof.html に記載されています。
baseof.html を layouts/partials/_defualts/ 内に入れ、追記します。

OGP を加えたいのですが？

🎈 Open Graph protocol | ふうせん🎈 FU-SEN

実は Hugo の内部テンプレートとして OGP と Twitter カードが備わっています。
日本では OGP と記載されるのですが、英語では通常 Open Graph 表記です。

Internal Templates Open Graph | Hugo

しかし、これを知らないのか、テーマでは意外と使われていません。
/layouts/partials/head.html などのヘッダ部分でこれらを加えます。

{{ template "_internal/opengraph.html" . }}
{{ template "_internal/twitter_cards.html" . }}

おそらく OGP を使用するなら、画像も適用したいでしょう。
画像は images ですが、複数の画像を指定できるようになっています。
config.toml では次の表記です。省略時の画像になります。

[params]
  images = ["/images/ogp.png"]

記事ファイルなどの .md ファイルで入れる Front Matter 部分で
通常使われている YAML では次の表記です。これで記事毎に画像を変えられます。

---
images:
- /images/ogp.png
---

SNS などでは重要要素になりますので、公開前に hugo server からソースを表示し、
目的の出力をしているかよく確認して下さい。

テーマによっては独自に OGP の実装を行っている場合があります。

ブログテーマを Web サイト向けに使用できますか？

可能ですが、ちょっと手間が必要で、テーマによって対応が異なります。
themes/テーマ名/layouts/index.html を変更する必要がありますので、
layouts/index.html へコピーして編集します。

主に次のいずれかになります。

themes/テーマ名/layouts/single.html と同等に置き換えます。
適切な場所に {{ .Content }} を加えます。ここに .md ファイルの内容が入ります。

完全に .md ファイルの内容にする場合は、記事一覧表示部分を削除しますが、
あえて記事一覧表示を残してページのメニュー一覧に改良する事もできます。
この場合 .md ファイルで weight を使って表示順を指定できます。
（weight は date よりも優先されます）

ページ生成は content/ 直下にファイル名.md で生成するか、
次を config.toml に入れた上で content/post/ に .md ファイルを入れます。
多くのテーマでは post 以外にする事もできますが、
一部 post で使用される前提で製作されているテーマがあります。

[permalinks]
  post = "/:slug/"

なお、themes 内はテーマの更新に伴って
git clone または git submodule update で更新するので、
themes 内のファイル変更・削除などは行わないで下さい。

Not Found ページは生成しますか？

Hugo では Not Found ページが 404.html で考慮されています。
Apache が採用されているサーバで .htaccess が使える場合は、次で適用できます。

ErrorDocument 404 /404.html

テーマで考慮されている場合、themes/テーマ名/layouts/404.html が存在しています。
独自のページにしたい場合は 404.html を layouts/ 内にコピーして編集して下さい。

RSS・サイトマップは生成しますか？

RSS は index.xml（フォーマットは RSS 2.0）、サイトマップは sitemap.xml で生成されます。
サイトマップは date の日時が反映されるので、クローラーの収集にも効果的です。

また config.toml に enableRobotsTXT = "true" を含めると robots.txt も生成されますが、
デフォルトでは単に 1 行の robots.txt を生成します。

User-agent: *

Sitemap などを含めるため、あえてこれを使わずに
static/ 内へ robots.txt を作っても良いでしょう。

これらは layouts/ 内で各テンプレートを生成できるので、
細かく制御する事もできます。

🎈 Hugo の robots.txt と Sitemap。| ふうせん🎈 FU-SEN

絵文字ではないアイコンはどのようにして表示するのですか？

Font Amesome が導入されているテーマが多いです。
上項目の HTML を有効にする事で、i タグに style を含めて表示できます。

Font Amesome
🎈 Font Awesome | ふうせん🎈 FU-SEN

public フォルダの日時がおかしくなっています。

hugo creating invalid timestamps in folder public #6161 | GitHub gohugoio/hugo issues

長く発生している不具合です。

これが原因で更に別の問題が発生している場合は、
hugo 実行後にコマンドで public ディレクトリの日時を更新して下さい。
多くの OS や環境では touch が使えます。Windows では Git Bash などで有効です。

hugo
touch public

Windows の PowerShell では、次のコマンドで更新する事もできます。

hugo
sp public LastWriteTime $(Get-Date)

.hugo_build.lock ファイルが生成されるようになりました。

What is the .hugo_build.lock file? | Hugo Community

Hugo 0.89.0 より、hugo のコマンド実行によって
.hugo_build.lock ファイルが生成されるようになりました。
これは正常な動作です。ファイルはそのままにしておいて構いません。

例えば hugo server を実行しながら hugo new ページ名 を実行するなど、
複数 hugo コマンド動作を行った場合に問題が発生するようになったため、
.hugo_build.lock ファイルで OS レベルのロック操作を行う事で、
これを防ぐようにした、との開発者の回答です。

Hugo

目次

公式・関連サイト

インストール

Hugo Extended

アップグレード・ダウングレード

Scoop

webinstall.dev・webi

Web サイト・ブログの新規作成

通常作業

フォルダ・ディレクトリ構成

archetypes/

content/

data/

layouts/

public/

resources/

static/

themes/

config.toml

その他

ファイル構成

config.toml

content/ 内

メニュー

Minify

Web サービスによる対応

Cloudflare Pages

Vercel

Q&A

正式表記は Hugo と HUGO どちらですか？

デプロイがとてもはやいと聞いたのですが？

最新版を素早く知る方法はありますか？

画像ファイルはどこに入れれば良いのですか？

コメントは付けられますか？

スマートフォン対応にできますか？

一部の表示がおかしいです

WARN 表示が出ています

.md ファイルに HTML 入れても認識しません

HTML ファイルに出力されないコメントはどのようにすれば良いですか？

強制改行したい場合は？

TOC（Table Of Content）で認識されない見出しを作るには？

ページ URL を変更したいのですが……

通常の Web サイトとブログを合わせたサイトを構築できますか？

独自の CSS を含めたい場合はどのようにすれば良いですか？

OGP を加えたいのですが？

ブログテーマを Web サイト向けに使用できますか？

Not Found ページは生成しますか？

RSS・サイトマップは生成しますか？

絵文字ではないアイコンはどのようにして表示するのですか？

public フォルダの日時がおかしくなっています。

.hugo_build.lock ファイルが生成されるようになりました。

ふうせん🎈 FU-SEN