Hugo のテーマに Mainroad を採用してサイトを移行する

February 16, 2023

Page content

Hugo のテーマとして今まで Docsy を使っていたけれど、積年の課題が残っていたのと放置している間に色々と崩れてきた。この際、ということで知り合いが Mainroad を使い出したのに背中を押されて手を出した。ココではセットアップの記録を tips 的に書き留める。

抱えていた課題

テーマの問題
- タグクラウドがない (Mainroad では “taglist” として機能が存在)
日本語表示が崩れがち
ちょっと飽きた

なので、あまり悪いことが多いわけではないです。あれもあれで十分使い続ける価値あるテーマです。

やったこと

ゼロからサイト構築

既存のサイトのディレクトリにテーマを追加するとわかりにくいことこの上ないので、まっさらな hugo site を作ってそこに theme を適用するのが一番良いと判断。

Hugo の Quick Start を見ながら
Mainroad の Demo Site 見て学習

Hugo 設定ファイルを修正

config.toml ではなく hugo.yaml というファイル名に rename and restructure した。どうも hugo v0.110 からは hugo.* を推奨しているそう。まだ移行期間なので古いファイル名でも見つけてくれるが、いい機会なので rename した。
hugo.yaml の編集
- demo config をいったん完コピして、自明なものを置き換え・修正
- Customization という記事も読んで取捨選択

コンテンツのテーマ依存部分の掃除

(元のコンテンツをいったん content-old とか適当なディレクトリに移動してから作業)
_index.html や _index.md を中心に、古いテーマ固有の方言や記法がエラーになるので、その辺どんどん削除していく
継続的に知識の整理を行う場所を docs
日記的にその時の出来事を書く場所を blog

Front Matter (記事メタデータ)

とりあえずカテゴリーとタグを使って仕分けをできることは確認した
```
categories:
  - Blog
tags:
  - Web
  - CMS
```

`hugo new` したときに作る markdown をテンプレート化したい

まず hugo new --help 読む。ふむ… -k が Archetype を指定できるらしい (アーキタイプ: 原型とか典型)。こいつがカギだ。

Archetypes 公式情報

アーキタイプ無指定で新しいブログ記事を作る場合、デフォルトの archetypes/default.md が使われる。

archetypes/default.md の例:

---
# Hugo Predefined Variables
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
categories:
- Draft # REPLACE with Blog, Tech, Productivity, etc.
tags:
- dummy # REPLACE with yours!
draft: true

# Mainroad-Defined Variable
thumbnail:
  src: 'https://placehold.jp/228B22/ffffff/90x90.png?text=SotSoG'
  visibility:
    - list
---

**Insert Lead paragraph here.**

## Section 1

Here comes some sentense

## Sub-Section 1.1

Some text.

hugo new blog/my-new-blog.md を実行

出来上がる content/blog/my-new-blog.md はこんな感じ:

---
# Hugo Predefined Variables
title: "My New Blog"
date: 2023-02-16T10:09:24+09:00
lastmod: 2023-02-16T10:09:24+09:00
categories:
- Draft # REPLACE with Blog, Tech, Productivity, etc.
tags:
  - dummy # REPLACE with yours!
draft: true

# Mainroad-Defined Variable
thumbnail:
  src: 'https://placehold.jp/228B22/ffffff/90x90.png?text=SotSoG'
  visibility:
    - list
---

**Insert Lead paragraph here.**

## Section 1

Here comes some sentense

## Sub-Section 1.1

Some text.

ToC (Table of Content) ある？

どうやら Hugo 自体がネイティブサポートしてるようなのでやっていく。参考: https://gohugo.io/content-management/toc/

The built-in .TableOfContents variables outputs a <nav id="TableOfContents"> element with a child <ul>, whose child <li> elements begin with appropriate HTML headings. See the available settings to configure what heading levels you want to include in TOC.

んでその the available settings はこれを config.toml に書き足す:

[markup]
  [markup.tableOfContents]
    startLevel = 2  # h2 から TOC にいれる
    endLevel = 3    # h3 まで TOC に入れる
    ordered = false # TOCのリストを番号なし箇条書きから番号付きに変える（邪魔）

Mainroad テーマだと themes/mainroad/layouts/partials/post_toc.html が実際にレンダリングしているので設定を書くだけで済む。けどテーマによっては自分でレンダリングを記述しないといけないかも。追加の仕方はこういう簡単な事例が参考になりそう。

既存のコンテンツの移植

用意した archetype を適用したいんだけど…スクリプト書く？ -> 特に先行事例見つけられなかったので自力で書いた。
- python-frontmatter 便利！だけど content というキーが front matter に存在すると動かない。残念な issue があるので、そこだけ都度発見しては手動で置き換えることで対処した
- pyyaml の yaml.dump がうまく日本語を扱えなかったのはなにか手があるのだろうか？愚直に pyyaml 使わないで移行処理を書いた

サイトの検索機能の導入

全文検索エンジンとかを統合せず、サイトに対する Google 検索のリンクへ飛ぶのが Mainroad の標準で用意している方法。実現する機能はいたってシンプルなんだけど、設定で一部ハマったので解説。

config.toml (hugo.yaml などとにかく Hugo 設定ファイル) で Search widget を有効化: Params.sidebar.widgets: [search] を含めるだけ。設定は標準で Google search を使うようになっている。 -> https://mainroad-demo.netlify.app/docs/customization/ の Search box widget セクションを確認
GitHub Actions などでコンテンツのビルドを行うそのタイミングで Base URL を指定する (-b オプション)。これに気づかずにずっとハマっていた。例：
```
hugo --minify -b https://wiki.georgeorge.com/
```

やってないこと

お化粧的に banner image 的なものは宣言できるのかな、トップページとかに。そのうち考えよう。