HexoからHugoへ乗り替える際、色々悩んでやっと日本語URL→半角英数字URLへの変換ができたので、備考録を残すよ。

変換手順

サイト設定をする

まずはURL（パーマリンク）の設定をします。
サイト設定（hugo.toml）に、タグとカテゴリのパーマリンクを設定（カテゴリは必要に応じて）。

1
2
3

[permalinks]
  tags = 'tags/:slug/'
  categories = 'categories/:slug/'

ちなみに、他のセクションの下（下記の例ではnote）にtagsディレクトリを入れたい場合は、単純に、

1

tags = '/note/tags/:slug'

とすれば良いです。

日本語タグにslugを設定

次に、各日本語タグ（カテゴリ）にslugを設定します。
まず、サイト設定（hugo.toml）で設定したパーマリンクになるtagsのフォルダを作り、その下にslugを設定する日本語タグのフォルダを日本語で作ります（例は「日記」タグ）。

• content
  • tags
    • 日記　←作ったフォルダ

ちなみに、他セクション内（下記例ではnote）にtagsディレクトリがあるパーマリンクを設定しても、contentフォルダ直下にtagsフォルダを作らないと上手くURL変換が効きません。

• content
  • note
    • tags　←ここに作っても×
      • 日記
  • tags　←必ずcontent直下にフォルダを作る
    • 日記

作った日本語タグのフォルダ内に_index.mdというMarkdownファイルを作り、以下のフロントマターを設定します（例はTOML形式）。

1
2
3
4

+++
title = '日記'
slug = 'diary'
+++

テンプレートを設定

ここまで設定できたら、あとは、例えばサイドバーなどにタグ一覧を出したい該当テンプレートのタグリンクのヵ所に

1
2
3
4
5

<ul>
 {{ range .Site.Taxonomies.tags.ByCount }}
 <li><a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a> ({{ .Count }})</li>
 {{- end }}
</ul>

とか記入すれば、設定ファイルに記載したタイトルとslugでパーマリンク（tags/diary/）が表示されます。
もし、これで上手く行かなかったら、slugではなくパーマリンクそのものを設定できるurlをフロントマターに設定します。
要はデフォルトのパーマリンクをフロントマターで設定するもので上書きするわけです。
slugと書いていた所をurlに直し、ルートからの絶対パスで設定します。（上記例だと、url = '/tags/diary/'） これで、該当箇所の

1

<a href="{{ .Page.Permalink }}">{{ .Page.Title }}</a>

が

1

<a href="/tags/diary/">日記"</a>

となります。

シングルページで使うなら、.Site.Taxonomiesよりも.GetTermsの方が、記事のフロントマターで書いた順にタグが並ぶのでオススメ。

1
2
3
4
5
6
7

<ul>
  {{- with .GetTerms "tags" -}}
    {{- range . -}}
      <li><a href="{{ .Permalink }}" rel="tag">{{ .Title }}</a></li>
    {{- end -}}
  {{- end -}}
</ul>

日本語URLが半角英数字URLになってスッキリ！

あとは、使用する日本語タグ（カテゴリ）全てに 上記と同じ設定（tagsorcategoriesフォルダ内に 日本語で 該当タグ（カテゴリ）名のフォルダを作り、_index.mdのフロントマターにtitleとslugorurlを設定する）をします。

タグ（カテゴリ）名に使用する記号によっては正しくエンコードされないものもありました。
確認した限りでは「・（黒丸）」と「×（全角のバツ）」はエンコードされず飛ばされてました（「WEB・PC関係」は「webpc関係」に、「はやて×ブレード」は「はやてブレード」になった）ので、記号を使用する場合は、一旦日本語で書いてプレビューでURLがどうなるのか確認してからフォルダを作成するのが吉かと。
また、フロントマターにurlを設定した場合は、各タグ（カテゴリ）のパーマリンクをそれぞれで設定しているので、サイト設定のpermalinksの項目で設定したタグ（カテゴリ）は削除しても良いです。

【おまけ】他セクション下にtagsセクションがくるようにパーマリンクを設定した際、ルート直下のtagsフォルダをレンダリングしないようにする

サイト設定（hugo.toml）でパーマリンクを

1

tags = '/note/tags/:slug/'

などにした際、ビルドするとちゃんとnoteフォルダ下にtagsフォルダが生成されます。
このnote/tags/フォルダは、ビルド前はcontent/tags/フォルダで、日本語タグ名で作成したフォルダを集めたルートになります。
つまりブランチバンドル＝リストページです。

リストページ扱いなので作成しなくてもプレビューやビルドの際に自動で_index.mdが補完されます。
そして、元々の場所がcontentフォルダ直下なので、プレビューやビルドされるとルート直下にもtagsというフォルダが作成され、その中にindex.htmlが生成されます。

つまりこう。（太字はフォルダ名）

• public
  • css　←staticフォルダにあったフォルダ
    • style.min.css
  • imgs　←staticフォルダにあったフォルダ
    • image.jpg
  • note
    • 20200101
      • index.html
    • 20210509
      • index.html
      • tags　←hugo.tomlでパーマリンクを設定したから作成されたフォルダ
        • diary　←_index.mdのフロントマターのslugから作成されたフォルダ
          • index.html
          • page
            • 1
              • index.html
  • tags　←ローカルで日本語タグ名フォルダを格納するために作ったフォルダ
    • index.html
    • page
      • 1
        • index.html

このpublic/tags/index.htmlは全タグの一覧リスト（つまり、「日記」とか「お絵かき」とかのタグ名のリスト）なので、必要ならテンプレートを整えると良いと思いますが、サイドバーやフッターメニュー等で一覧リストを出している場合は不必要かと思います。
これがindex.mdを内包するリーフバンドルならヘッドレスバンドルにすれば話は早いのですが、_index.mdを内包するブランチバンドルなので、明確にビルドしないように設定する必要があります。

contentフォルダ内のtagsフォルダ内に_index.mdを作成し、フロントマターに以下を設定します。

1
2
3
4

+++
[_build]
  render = 'never'
+++

フロントマターで設定できる _build オプションを設定しています。

• render ：いつページをレンダリングするか。
• never ：全てのページやリストに含めず、レンダリングしない。

これらを設定した後、hugoコマンドでビルドすると、ルート直下にあったtagsフォルダがレンダリングされません。
テキストのみの小さいファイルでも、どこにも使用されない不要なファイルをレンダリングするのは余計だと思うので、しないに越したことはないかと思います。

Hexoからの乗り換えで一番困ってたことだった

Hexoは標準機能として、URLマッピングが備わっています。
設定ファイル（config.yml）で以下のように設定すると、日本語タグも半角英数字に変換できていました。

1
2
3
4
5
6
7
8

tag_map:
  FLOWERS: flowers
  お絵かき: illust
  同人関係: dojin
  はやて×ブレード: hxb
  日記: diary
  感想文: review
  WEB・PC関係: webpc

この機能があったからWordpressから静的サイトジェネレーターへ乗り替える際、Hexoを選んだと言っても過言ではありません。

なぜならURLに日本語を含む２バイト文字を使いたくないから。

URLエンコードされて正しく処理されるとしても、エンコードされてだらだらと長ったらしい文字列が並ぶよりも、半角英数字で見やすい＆わかりやすいURLの方が精神的にも安心します。
Wordpressもタグやカテゴリなどには別途slugが割り当てられていたので、こういうURLマッピングができるって普通なのかと思ってたんですけど、Hugoはそうじゃなかったんですよね……。
Hexoに完全に決めるまでは、HexoとHugoを平行して触っていたんだけど、ここだけどうにもならなかったのでHexoにした、みたいな。
で、紆余曲折ありHexoから乗り替えを決意してからの勉強中に何とかなったので、記事にしようと相成りました。

……しかし、ググったら既に解説してるサイトさんがあったのか……もっとちゃんと検索すればもっと早くヒントが得られたかもしれなかった……(笑)

参考サイト