Hugo 作業備忘録

2025-10-07 · 8 分で読了 · Hugo

Hugo の始め方

Hugoはssg(static site generator)との名前が示すとおり、コンテンツだけをmdまたはorg形式などで用意すれば、他の細かいことは全部template(theme)に応じて生成し、見栄えのいいwebサイトを構築してくれます。

Hugo本体はapt install hugo

themeによらない、一般的な始め方

Hugoを用いたサイト構築の一般的な始め方は、HugoのQuickStartにあるように、

1$ hugo new site <hoge>
2$ cd <hoge>
3$ git init
4$ git submodule add <theme>
5$ hugo server -D

とした後、browserから

localhost:1313

としたら、拝めます。-Dはdraftも表示の意味(ファイルのfront matterで設定)。

ただ、themeにより、対応するhugoのversionやできることが異なるようなので、 themeを決めてから各テーマのdocumentを参考にして作業したほうが良いようです。

theme clarityを使う始め方

Clarityを使いました

必要条件: the extended version of Hugo 0.91.0 or above と書いていますが、最新にしないと動かないかもしれません。

2024.9.18作業、theme.tomlでは min_version="0.128.0"になってた。

bookwormでは

1$ hugo version
2hugo v0.111.3+extended linux/amd64 BuildDate=2023-03-16T08:41:31Z VendorInfo=debian:0.111.3-1

だったので、最近のClaityをDLすると、動作しなくなってしまいました。

そこで、現状の私の環境のgo.modは、昔のmoduleを呼び出しました(下方参照)。

2025.8.12 trixie update

trixieにupdateしたら、最近のClarityで動作しました。

hugo v0.131.0+extended linux/amd64 BuildDate=2024-09-03T01:15:37Z VendorInfo=debian:0.131.0-1

入れ替えるのがめんどいので、調子こいてgo.modだけを書き換えると、summaryの表示がヘンになってしまいました^^;

Clarityの導入

3通りあるけど、以下の方法がおすすめだそうです。

themeをmoduleとして読み込む。

goはinstall済み(hugoをaptしたときに入った。(macではbrew必要))

1$ hugo new site <sitename>
2$ cd <sitename>
3$ hugo mod init <sitename> -- go.mod, ができた
4$ wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz
5$ cp -a ./hugo-clarity-master/exampleSite/* . && rm -f config.toml

このあと、

theme設定

emacs ./config/_default/hugo.toml
  theme=hugo-clarity を
  theme=["github.com/chipzoller/hugo-clarity"]に変更

ただし、私の環境では新しいmoduleではerrorになったので、 go.modで呼び出しているmodule(hugo serverを実行したら以下が追加される) を古いものに書き換えています。

//require github.com/chipzoller/hugo-clarity v0.0.0-20240923132253-174a5e638704 // indirect
//require github.com/chipzoller/hugo-clarity v0.0.0-20250302180814-2c9a7b6d3937 // indirect
require github.com/chipzoller/hugo-clarity v0.0.0-20240429154213-8412edb36941 // indirect

サイト参考資料からの変更点

tarした本体はrmせずに参考用に残しています。 ##&& rm -rf hugo-clarity-master
cp -a ./hugo**の./を追加
clarityの環境設定方法は他のthemeとやや異なり、config.tomlなどの設定ファイルがすべてconfig/に移動しています。したがって、ここでrmしています。

環境設定ファイル名は、config.tomlから、hugo.tomlに変更されています。

2025.8.2 trixieのとき、変更無しで動いた!:とおもったら、他のファイルが昔のままならsummaryの表示がヘンになりました。(- -);

1module hoge
2go 1.24.4
3require github.com/chipzoller/hugo-clarity v0.0.0-20250514185450-16f2e94b0bce // indirect

demoをみる

1$ hugo server -D

とした後、browserから

browserで以下のURLを指定すると、サンプルが見れます。

localhost:1313

-Dはdraftも表示,各mdのfrontmatterで設定しています。 -Dを省略すると、draft=falseの文書のみ表示します。

update方法は以下のように紹介されています

To pull in theme updates, run
hugo mod get -u github.com/chipzoller/hugo-clarity
You can also update all your Hugo modules with
hugo mod get -u ./...
-- read more about updating Hugo modules.

Clarityの見た目を変えたいときは、別ページを参考。

Hugo用のcontentsを作る

雛形をcpして作成.

1 $ hugo new content/post/my-first-post.md

雛形はarchtypes/default.md

サイトの案内にはposts.md,default.md の順に探していくと書いてあるが、逆のよう。 default.mdが優先のよう。

テンプレートを用いたファイル生成:任意の雛形が作れるようです。
archtypes/hoge.mdというファイル hoge.mdがあれば、hugo new hoge/in.mdとした時、 content/hoge/以下のファイルの雛形として使用されるようである。つまりarchtypes/hoge.mdのhogeがdirectory名の識別として有効になるようである。

コンテンツ(文書)の書き方

mdまたはorgの書式で作成、名前は任意。公開時にはsitename/filename/index.htmlとなるみたい。
文書が完成するまで見せたくないときは、frontmatterのdraftをfalseにする。
図を含むコンテンツは、1つのfolderにindex.md(本文)と図を保存するdir(名前は任意)を作成する。本文中で図を表示する時は./dirname/fig.pngでok これがbundleページの意味???

任意のfolder 作成 ok

folderはcontent,content/post,がデフォルト
- content/の下は任意のdir作成ok。
- content/post/にあるファイルには、configで指定するいろいろなおまじないが効くようである。
- postの名前は、params.tomlのmainSectionsで設定可能かな?
content/に about.md,archives.md,search.mdあり。archiveに目次をつくってみました。
ページヘッダのmenuは config/_default/menus/menu.en.toml

[[main]]
name = "Archives/Index"
#url = "post/rich-content/"
url = "archives/"

content/archive.mdはヘッダだけ

mdの書式??

frontmatterの書式に—(ハイフン3つ)と+++がある。

—(ハイフン3つ)はyaml:

YAMLは人間が読みやすく書けることを重視したフォーマットで、構造はインデント（スペースやタブ）で表現されます。引用元

+++はTOML:

TOMLは構造化されたデータを表現するためのformat

{}はJSON

JSONは軽量なデータ交換フォーマットで、データを階層的なキーと値のペアの形式で表現します。これらのデータは、ダブルクォートで囲まれた文字列で表現され、数値、真偽値、nullもサポートされています。

markdownでは3つ以上のハイフンは罫線になるので変換時注意

自分で作るtemplate　参考先

Hugoのサマリの落とし穴

デフォルトは冒頭70単語(半角)表示されるようです。

制限したいときは、

<!--more-->

と本文にかけば、この上の行までサマリ表示の抑制ができる。引用元

日本語はイメージ通りにならないこともあるので、以下の日本語設定(2byteカウント) すること

Hugoの日本語設定

日本語設定

hugo.tomlに hasCJKLanguage=true としたら文字カウントok 引用元
configureでは、hasCJKLanguage .Summary, .WordCountで有効

frontmatterに設定は isCJKLanguage=true WordCount,FuzzyWordCount,ReadingTime,Summary

Hugoを実行するとpublicの下にコンテンツが展開される

post/filenameが post/filename/index.htmlになるみたい。
public/post/rich-content/index.html に展開される name = "About" url = "about/"
content/about.md 内容たくさん public/about/index.htmlに展開
config/_default/params.toml の mainSetions =["post"] に指定したfold内のcontentsだけが、表のpageに表示される

フォルダ内に複数の文書を置くときは_index.mdを作成する

front matterだけあればいいようです。適当にcp。

hugo _index.md

ページのネスト

Hugo manual

ページのheader

type=search, sections
searchPage=true
layout: archives
series:
aliases:
descriptions

blogもある??

taxonomy(分類)

hugo.tomlに[taxonomy]として、色々設定ある。

taxonomyの使い方の説明

asciidocを変換可にする(検討中)

以下の方法は単純な変換方法で、github/actionsで動かすにはもっと修行がいるようです。(以下では^^;;)

asciidocをsecurity追加する。

[[https://stackoverflow.com/questions/71058236/hugo-with-asciidoctor][参考サイト]]

hugo.tomlに以下追加:config.tomlでは効かない(obsolete)

[security.exec]
allow = ["^dart-sass-embedded$", "^go$", "^npx$", "^postcss$", "^asciidoctor$"]
osEnv = ["(?i)^(PATH|PATHEXT|APPDATA|TMP|TEMP|TERM|RUBYLIB)$"]

RUBYLIBを追加している

または別の方法

[security.exec]
allow = ['^(dart-)?sass(-embedded)?$', '^go$', '^npx$', '^postcss$','^asciidoctor$']
osEnv = ['.*']

どちらがいいのかな?

Hugo manual

HUGO docs

ここからcontent managementへ行くと Front matter Taxonomy Summaries などなどいろいろ解説あり

一部だけ日本語訳あり

shortcodeの解説

DOCS->Shortcodes->Figure

hugo.ssg説明, 最初の参考サイト

ssgの説明 https://fand.jp/what-is-static-site-generator/

hugoわかりやすかった https://qiita.com/nonchang-net/items/3d2d2a726c6294d333a4

hugo 始め方手取り足取り https://zenn.dev/harachan/articles/a043e9a756cae4

ここもわかりやすい。githubにpushまで書いてある。 https://www.pc-koubou.jp/magazine/30737