Hugo

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

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

公式・関連サイト

• Hugo - 公式サイト
  • Hugo Documentation - ドキュメント
  • Hugo Themes - テーマ
• Hugo Community - 掲示板
  • 日本語 - 日本語でも投稿可能です
• GitHub - gohugoio / hugo
  • Releases - ダウンロード
  • Issues - 不具合報告
• Twitter - @GoHugoIO

インストール

GitHub から直接実行ファイルをダウンロードし、path を通します。

Releases | GitHub - gohugoio/hugo

Homebrew・Chocolatey・Scoop を使用している場合は、
そちらからパッケージインストールも可能です。

Install Hugo | Hugo Documents

Windows では PowerShell・コマンド プロンプト・Git Bash、
macOS では ターミナル などを起動し、次のコマンドを入れます。

hugo version

Hugo Static Site Generator v～ の表示でインストールできています。

Hugo Extended

ダウンロード・パッケージの一覧には extended 表記も存在します。
Extended は SASS・SCSS に対応したバージョンです。
一部のテーマで使用されているため、Extended 必須の場合があります。

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

GitHub から実行ファイルをダウンロードした場合は、
同じ方法で最新版をダウンロードし、ファイルを上書きして下さい。
問題があって古いバージョンに戻したい場合も同様です。

Scoop

🎈 Scoop | ふうせん🎈 FU-SEN

Scoop を用いている場合、容易にインストールできます。

scoop install hugo

更新も簡単です。

scoop update hugo

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

それでは一つ Web サイト・ブログを作成してみる事にします。
cd 場所 で Web サイト・ブログの構成ファイルを置く場所に移動します。
複数環境の共有やバックアップを目的に Dropbox なども使っても良いでしょう。

次を実行します。サイト名 はディレクトリ（フォルダ）になります。
そのため、サイト名 は英数が無難です。
サイト運営者 は ドメイン名（gohugo.jp.eu.org など）にしています。

hugo new site サイト名

テーマを決めます。

Hugo Themes

テーマの詳細ページから Download または Homepage で
GitHib のプロジェクトページが表示されます。
このテーマファイルを git clone または git submodule add でダウンロードします。

cd サイト名/themes/
git clone リポジトリ

テーマファイルのディレクトリに入ると、exampleSite/ ディレクトリがある事が多いです。
この exampleSite/ 内を サイト名/ 下にコピーします。
この時 config.toml は上書きして構いません。これで準備が整いました。

通常作業

追加・変更は cd サイト名 で移動しておきます。config.toml と複数のディレクトリがあるところです。

hugo server

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

テーマを編集する必要がある場合、 themes/テーマ名/layouts/ 内のファイルを
layouts/ 内にコピーしてから編集して下さい。
themes/ 内はテーマがバージョンアップした時に更新するため、
ここのファイルを編集すると更新で抹消されてしまいます。
themes/テーマ名/static/ 内も同様に static/ 内へコピーして編集します。

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

完成したところで、cd サイト名 へ移動し（config.toml と複数のディレクトリがあるところ）
次のコマンドでビルドします。
通常 1 秒もかからず、ブログなどページ数が多くなっても数秒～数十秒で完了します。

hugo

この時 Minify が可能です。

public/ 内に index.html などが生成されます。
出力先を public/ から変更する場合は config.toml に publicDir で指定します。

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

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

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

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

ファイル構成

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

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 © 2020 
<a href="https://balloon.im/" 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: 2020-01-09T16: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: 2020-01-09T16: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 サービスによる対応

Vercel

▲ Vercel
🎈 Vercel

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.78.1 にしています。

{
  "build": {
    "env": {
      "HUGO_VERSION": "0.78.1"
    }
  }
}

Fly

Fly
🎈 FLy | ふうせん🎈 FU-SEN

Fly では flyctl の builder 選択に hugo-static があります。
flyctl apps create または flyctl init で選択します。

? Select builder:  [Use arrows to move, type to filter]（次を選択）
  hugo-static
    Hugo static build with web server builtin

または fly.toml に次の記載を含めます。

[build]
  builtin = "hugo-static"

fly.toml は config.toml と同じ場所に置いておき、
hugo server と同じところで flyctl deploy を実行します。

なお、2020年12月現在、Hugo のバージョンは選択できないようで、
ソースでは Hugo 0.74.0 で固定されてあるようです。

Q&A

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

HUGO はロゴタイプとして使用されています。ロゴと公式サイト（gohugo.io）の左上のみです。
一方 Hugo は全般的によく表記されています。したがって、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

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

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

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

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

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

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

ページ生成は content/ 直下に ファイル名.md で生成するか、
次を config.toml に入れた上で content/post/ に .md ファイルを入れます。

[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)