Theme なしで Hugo を使いはじめる

03 April 2025

普段コードをあまり書かない人とも共同で扱うかもしれないことから，(jekyll に比べて環境構築が楽かもしれない) hugo の利用を検討して，このブログもその一環で作成している．公式の quick start 通り theme を使うとむしろ機能がわかりにくいので，素の状態から使い始めてみる的なやつを，随時更新しながらメモ書きとする．

本当の quick start

公式の quick start では hugo new site quickstart して次に git submodule で theme をインストールしている
しかし，たとえばこの themes/ananke/layouts/ に置いてあるファイルは，普通にプロジェクト直下の layouts/ に置いていても同様に働く（むしろ，そういうのをまとめてパッケージ化したのが theme といって良さそうだ）．
- しかし，一気に theme 全体の理解をするのは大変っぽい．
そこで，hugo new theme でできる空のテーマから必要そうなファイルをプロジェクト直下にコピーしていき，機能の理解を進めながらシンプルにやってみることにする．

構造

hugo new theme my-theme でできるのはこんな構造だ

./
├── archetypes/
│   └── default.md
├── assets/
│   ├── css/
│   │   └── main.css
│   └── js/
│       └── main.js
├── content/
│   ├── _index.md
│   └── posts/
│       ├── _index.md
│       ├── post-1.md
│       ├── post-2.md
│       └── post-3/
│           ├── bryce-canyon.jpg
│           └── index.md
├── data/
├── hugo.toml
├── i18n/
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── home.html
│   │   ├── list.html
│   │   └── single.html
│   └── partials/
│       ├── footer.html
│       ├── head/
│       │   ├── css.html
│       │   └── js.html
│       ├── header.html
│       ├── head.html
│       ├── menu.html
│       └── terms.html
├── LICENSE
├── README.md
├── static/
│   └── favicon.ico
└── theme.toml

documentation の Directory structure にある通りだがざっくり，

archetypes/ が hugo new content で新しい記事/ページを作る時の雛形
assets/ は見た通り
content/ が実際のページ・記事
hugo.toml が設定ファイル
layouts/ が，content/ にあるいろいろとか，トップページとかを実際の形にするためのテンプレート
static/ にあるファイルはビルド後 pubic/ 直下に置かれる

みたいな構造になっている．

このうち archetypes/default.md は書きながら適宜便利そうなやつを追加していけば良さそうで，サイトの機能という意味では主に layouts/ を触っていくことになる．

layouts

`layouts/_default/home.html`

上の空の theme の layouts/ をまるっとコピーすると，これがサイトの root で見られるページを作る（はず）．たとえば

{{ define "main" }}
	{{ .Content }}
	<div class="the-posts">
		<ul class="post-list">
		{{ range site.RegularPages }}
			<li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a> &mdash; {{ .Date | time.Format "02 January 2006"  }}</li>
			<!-- {{ .Summary }} -->
		{{ end }}
		</ul>
	</div>

	<div class="links">
		See <a href="/posts">all posts</a> or <a href="/tags">tags</a>.
	</div>
{{ end }}

を今は採用している．

テンプレートのややこしい所はあるがまあ最終的には見たままの動きではある

`layouts/_default/list.html`

デフォルトではこんなふうになっている．

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  {{ .Content }}
  {{ range .Pages }}
    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
    {{ .Summary }}
  {{ end }}
{{ end }}

最初の時点からなんか色々思ったより表示されるな…？となるのはこいつの力，というのも…

`layouts/tags/tag.terms.html.html`

あんまりそれっぽいテンプレートがないのに色々表示される，とか，なぜかここの更新がこっちに反映されないとか，ここの更新がこっちにも影響してしまう…とかが色々出てくる．見るべきは lookup order のドキュメンテーション．例えば，タグの一覧を示すページはここを見て，layouts/tags/tag.terms.html.html というファイルを作ると，専用のテンプレートとして設定できる．

そんなファイルが存在しないうちからなんとなくそれっぽいものが表示されていたのは，lookup order の下の方に layouts/_default/list.html があるから．リスト化するやつはだいたいこれね，という感じでよしなに作られていたわけだ．

同様に個別のタグのページは例えば，layouts/tags/term.html.html に

{{ define "main" }}
	<h2>Posts tagged with: {{ .Title }}</h2>
	{{ .Content }}
	<div>
		<ul class="article-list">
			{{ range .Pages }}
			{{ $dateMachine := .Date | time.Format "2006-01-02T15:04:05-07:00" }}
			{{ $dateHuman := .Date | time.Format "02 January 2006" }}
			<li>
				<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>
				<time datetime="{{ $dateMachine }}">{{ $dateHuman }}</time>
			</li>
			{{ end }}
		</ul>
	</div>
{{ end }}

のようにする．

Taxonomy

Hugo独自のもの…だと思うが，普通の tag とか category を包括する形で，種別・そのなかのメンバ・どのページにそれが紐づけられているか，が概念化されている．
Taxonomy, Term, Value の区分を含めて，やはりこれもドキュメンテーションがわかりやすい．
ひとまず以下の設定で，タグだけ有効にしている．このときタグ一覧のページとかは上記の layout で作られているわけだ．

[taxonomies]
  tag = 'tags'

こんな感じで紐解きながらちょっとずついじりながら，が良さそう．しばらくは随時構造を少しずつ調整していくので，その都度ここに追記するかより細かい記事を投げていくかしていきたい．

tags:

hugo