2023年5月21日追記
本記事で公開後、ほったらかしにしていたのですが、最近、アクセスしてローカルでは表示できているのに、Cloudflare Pages では正しく表示できないページがあることが判明しました。
(会社員の頃には、リリース後に全コンテンツを必ず点検する癖がついていたのですが、忙しさにかまけて、リリースしたコンテンツの確認を怠ってしまいました。反省。。。)
「関数」セクションは全滅、という状態で、アクセスした方には不便をかけて、申し訳ありませんでした。
自分が試す限り、Cloudflare Pages のディレクトリ名、ファイル名には、以下の制限があるようです。
- ディレクトリ名
functionsは、ビルド対象とならない - ファイル名に、英字の大文字、
.を指定すると、リンク先の対象とならない
他に、正しい回避方法を知っている方は、本記事にコメントで教えていただけると助かります。
なお、Bootstrap 5.3.0-alpha3 への対応はしましたが、特に alpha3 対応で修正が必要なことは分からず、こちらの修正なしで動作しています。
また、Google Search から警告が届いているのですが、それの対応ができていないので、Google 検索で問題が起きているかもしれません。
Qiita の過去記事「Hugo ドキュメント (日本語訳) を公開しました」にて、サイト公開の告知をしました。
しかし、後述のような問題点を解決するために、利用していた Hugo テーマを変更するとともに、ホスティングサービスを GitHub Pages から Cloudflare Pages に変更して、新しく公開し直しました。
新しいサイトは、以下の URL です。
旧公開サイトの問題点
この場合、本家の Hugo ドキュメントサイト と同じ Hugo テーマである
- gohugoioTheme - Hugo サイト用の Theme リポジトリ
を利用し、本家の Hugo ドキュメントサイトに日本語版を追加する形で公開していました。
しかし、この gohugoioTheme には、多国語化に関し、以下のような問題点がありました。
- テンプレートで使用されている "See Also"、"Read More"、"Syntax" が多国語化されていない
- i18n/en.yaml および ja.yaml を追加し、テンプレートでこれらを参照するように修正した
- ショートコード (datatable-filtered.html, databtable,html, gomodules-info.html, page-kinds.html) が英語表記で、本文にそのまま引用される
- それぞれの日本語訳ショートコードを追加し、日本語本文ではそれら日本語ショートコードを引用するように修正した
他に、アクセスしやすくするために、以下のような修正も行っていました。
- CLI (コマンド) をサイドメニューにすべてリストするようにした
しかし、以下の問題は解決することができず、日本語版サイトにおける最大の課題となっていました。
- 出力される sitemap.xml を Google アナリティクスに登録しても、列挙したページが Google 検索されない
- このため、代表的な日本語ページを個々に Google に URL 登録していた
- サイト内検索では、英語版ページしか検索対応していない
新しい公開サイトへの変更点
Bootstrap 5.3.0 の採用
Bootstrap の最新版は、2023年4月3日現在、5.3.0-alpha3 と安定版ではありませんが、
Bootstrap 5.3 ドキュメントサイト は Hugo テーマとして、以下の利点を持っています。
- ダークモード対応
- レスポンシブ対応
- sitemap.xml 対応
そこで、公式サイトとは異なり、Bootstrap 5.3.0-alpha2 1 をベースに公開サイトを構築することにしました。
Bootstrap 5.3.0 サイトのテーマ化
Bootstrap 5.3 ドキュメントサイト は、Hugo テーマとして利用するために、Hugo モジュール化することにしました 2。
しかし、Docsy や Write-Only が行っているように、
以下のドキュメントに記載されている理由により、Bootstrap/site/assets/scss/_vendor フォルダを別リポジトリ (別モジュール化) する必要がありました。
- cmd/go: non-top-level packages ending in "/vendor" are omitted from module zip files #37397
- Bootstrap 4.4.1's SASS fails in Hugo #6945
- Turning docsy theme into a hugo module #806
当初は、Docsy テーマと同じようにモノレポで対応していましたが、更新処理が面倒であったのと、他の書かれた記事で推奨されていなかったため、
Write-Only と同じように別リポジトリとして管理することにしました。
今回の日本語版ドキュメントサイトで利用する Hugo テーマに関連して作成したリポジトリは、以下の3つです。
- hugo-widebs5-dependencies - Bootstrap 5.3.0-alpah のバグ回避
- hugo-widebs5-theme - Bootstrap 5.3 対応の新しい Hugo テーマのリポジトリ (Hugo モジュール対応)
- hugo-widebs5-example - 上記テーマを利用した動作確認のためのサンプルサイト
Bootstrap が更新されると、上から順番に Hugo モジュール (Go モジュール) を更新する必要があり、Bootstrap が安定版をリリースするまではメンテナンスに苦労しています。
幸い、「v5.3.0-beta のリリースはなく、次のリリースが v5.3.0 の正式版となる」という記述を読んだので、v5.3.0 正式版のリリースと共に、Hugo モジュールを管理する go.mod ファイルのバージョン指定を固定する予定でいます。
注意: 上記のテーマは、作業中 (WIP) であるため、参考にするのは一向に構いませんが、これを利用してのサイト構築は非推奨とします。
他の人が利用できるように Hugo テーマ化するには、Bootstrap が安定版である v5.3.0 を公式リリースした後、
さらに Bootstrap ドキュメントサイト独自のファイルを削除するなどの残作業が必要です。
備考:
Hugo モジュールについては、現状、よく理解できていません。Go モジュールは、ローカルにgit cloneでキャッシュし、キャッシュしたファイルを用いています。
Hugo モジュールは、git cloneした各ディレクトリ + Hugo 設定ファイルconfig.{yaml,toml}をキャッシュし、
設定ファイルのmodule.importsやmodule.mounts指定を参照して、インポートした Hugo モジュールファイルにアクセス可能にしているようです。
日本語によるサイト内検索機能
過去に開発された Hugo テーマで利用されている検索ライブラリおよび検索サービスには、以下のものがあります。
- (サイト内) 検索ライブラリ
- 検索サービス
-
Algolia
- DocSearch - OSS のみの利用が無償
- Bonsai.io = ElasticSearch + Netlify
- Amazon OpenSearch Service
-
Algolia
このうち、検索サービスは基本、有償であるため、検索ライブラリの内、ベンチマークで性能の良いとされる FlexSearch を採用することにしました 3。
Flexsearch を採用している Hugo テーマに、Zen テーマがあるため、検索機能組み込みにあたっては、Zen テーマを参考にしています。
記事 (Gatsby) Flexsearch × Kuromoji による日本語フレンドリーなサイト内検索の追加 にあるように、
Flexsearch のみの検索では日本語対応が不十分らしいですが、Kuromoji.js / kuromojin を用いた
日本語の形態素解析への対応は現状、できていません。
参考にしたサイト
-
Bootstrap 5.3 ドキュメントサイト - 本家、英語版
- Bootstrap5 設置ガイド - 最新版 (v5.3.0-alpha3) に対応するよう更新している日本語版ドキュメントサイト
- Bootstrap 5.0 日本語ドキュメントサイト - LINE Corporation が日本語訳を行い、本家サイトにもリンクされているが、5.3 に追随していない
- Hugo モジュール関連
- Go モジュール関連
- 公式 Go Modules
- 公式 Go Modules Reference
参考にしたテーマ
- Docsy - Google が開発している Bootstrap ベースの Hugo テーマ
- Write-Only - Bootstrap ベースの Hugo テーマ
- Zen - Flexsearch.js を用いたブログテーマ