静的サイトジェネータ Hugo(ヒューゴ)についてまとめています。
詳細な日本語説明サイトもできているため、簡単な説明に留めています。
詳しい説明は必要に応じて検索してみて下さい。


インストール

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


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

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

次を実行します。サイト名 はディレクトリ(フォルダ)になります。
そのため、サイト名 は英数が無難です。
Hugo のつかいかた。運営者 は ドメイン名(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 によるアップロード・公開


ファイル構成

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

config.toml

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

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

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

copyright = """
Copyright © 2020 
<a href="https://jpn.balloon.im/" target="_blank">ふうせん🎈 Fu-sen.</a>
"""

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

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

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

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

---
title: "Hugo のつかいかた。"
date: 2020-01-09T16:20:00+09:00
---

# Hugo のつかいかた。

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

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


メニュー

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://gohugo.jp.eu.org/"

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

Menus | Hugo Documents


Minify

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

hugo --minify

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

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


CLI によるアップロード・公開

Hugo で制作した場合、アップロード・公開もコマンドで行うと便利です。
ここではいくつか記載します。いずれも無料で使用できるサービスです。
(転送量・ストレージ容量など、無料で使える制限がある場合があります)

一部サービスではビルドをサービス側で行う事もできますが、
ここではローカルのパソコンでビルドする前提で記載しています。

Netlify

Netlify

Netlify では GitHub・GitLab・Bitbucket で git push されたリポジトリから pull し、
Hugo でビルドして公開するのが一般的な使われ方です。

Host on Netlify | Hugo Documents

これとは別に CLI で公開する事もできます。

hugo
netlify deploy --dir=public --prod

Get started with Netlify CLI | Netlify Docs

Firebase Hosting

Firebase

Firebase Hosting は public/ 下が公開対象です。
これは Hugo と共通しているので、デフォルト設定のまま使用できます。

hugo
firebase deploy

Host on Firebase | Hugo Documents

ZEIT Now(zeit.co・now.sh)

ZEIT

now.json は static/ 内に入れて hugo して下さい。

ローカルのパソコンでビルドする場合は次となります。

hugo
now --prod public

package.json への追記で ZEIT Now 側でのビルドが可能です。
更に GitHub・GitLab・Bitbucket との連携も可能で、 git push でビルド・公開も可能です。

Create a Hugo Website and Deploy It with ZEIT Now | ZEIT Guides

Surge(surge.sh)

Surge

~.surge.sh は SSL が有効ですが、Google などでインデックスされません。
Surge を用いた公開前提の Web サイト・ブログは独自ドメイン使用必須となります。
しかし、独自ドメインを SSL 化する場合は有料プランにする必要があります。
代わりに Cloudflare 側で SSL 化する事でドメイン費用以外は完全無料・SSL 対応で公開ができます。
(他のサービスと異なり、この方法はサイト数・転送数の制限なく完全無料で使えます)
Hugo のつかいかた。は Surge+Cloudflare で公開しています。

Cloudflare

CNAME は static/ 内に入れて hugo して下さい。(記載は GitHub Pages に同じ)

hugo
surge public

Netlify CMS

Web ブラウザ上で content/ 内のページ作成・編集を行う事ができます。

Netlify CMS

注意があります。

Start with a Template | Netlify CMS

GET STARTED で入ったこの画面で Hugo を選択した場合、
コーヒーデザインの仮テーマが導入されます。そのままでは使えません。
しかし、このテーマを変更する場合は、生成した GitHub・GitLab リポジトリから
Themes/ 内と config.toml を変更する必要があります。

そのため、通常の手順で Hugo の Web サイトを生成した後、Git リポジトリにして、
Netlify CMS 関連のファイルを追加する方が良いかもしれません。

Add to Your Site | Netlify CMS


Q&A

Hugo と HUGO 正しいのは?

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

最新版を素早く知る方法は?

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

GitHub - gohugoio / hugo

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

画像を入れるところは?

画像は static/ 内に入れて下さい。 hugo で構成そのまま public/ 内に入り、
config.toml の baseurl で記載している URL 下で公開される事になります。
static/ の中に img/ や images/ 等のディレクトリを生成しても良いですが、
ブログの場合は画像が多くなるので、更に年・月で分けても良いでしょう。

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

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

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

config.tomlpermalinks を使用します。ない場合は追加、ある場合は変更します。
通常ブログで使われる 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

強制改行したい場合は?

行末・改行直前で \(半角 \ または 半角 ¥)を入れます。

上項目で HTML を有効にしている場合は <br> でも構いません。

独自の CSS を含めたい場合は?

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

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 で生成されます。

なお、config.toml に enableRobotsTXT = "true" を含めると robots.txt も生成されます。
これを使わずに static/ 内へ robots.txt を作っても良いでしょう。

絵文字ではないアイコンは?

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

Font Amesome

例えば上の は次の記載です。

<i class="fab fa-font-awesome"></i>

次のところでアイコンを検索できます。クリックすると貼り付ける i タグが表示されます。

Icons | Font Amesome

テーマによってバージョンが古く、class への記載が異なる場合があります。