Hugo

静的サむトゞェネヌタ 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 から実行ファむルをダりンロヌドした堎合は、
同じ方法で最新版をダりンロヌドし、ファむルを䞊曞きしお䞋さい。
問題があっお叀いバヌゞョンに戻したい堎合も同様です。

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 ブラりザの衚瀺に即反映されたす。
䞻に次のずころを远加・線集する事になりたす。

  • config.toml - サむト党般の蚭定
  • content/ 内 - ペヌゞ・ブログ蚘事通垞は .md ファむル
  • static/ 内 - 画像・JavaScript・CSS などこの䞭はそのたたコピヌされたす

テヌマを線集する必芁がある堎合、 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 を含めたい堎合はどのようにすれば良いですか

テヌマによっお異なりたす。䞻に次のいずれかです。

  • 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/ 内に入れ、远蚘したす。

ブログテヌマを 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 ファむルを入れたす。

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