Hugo のサイトで Bootstrap 4→5 アップグレードする手順例

Hugo で利用している Docsy テーマのBootstrap 5 対応予定について調べたところですが、22Q4 での対応が予定されていて間近であることから、サイトの Bootstrap 5 対応の準備をしました。この記事では、 Hugo で作成しているサイトでの Bootstrap 5 対応の一例を記載します。

先日の記事は以下を参照してください。

Hugo テーマ “Docsy” の Bootstrap 5 対応

https://fand.jp/bootstrap-5-support-for-hugo-theme-docsy/

Hugo のドキュメントサイト用テーマ Docsy の Bootstrap 5 対応動向の確認

Bootstrap 5 アップグレードガイド

英語 - https://getbootstrap.com/docs/5.0/migration/
日本語 - https://getbootstrap.jp/docs/5.0/migration/

当然サイトの作り込みによってBootstrap への依存度は異なるため、アップグレードガイドをしっかり読み込んで確認しなければ最適解は出せませんが、とりあえず最新バージョンを適用してみてどこまで表示が崩れるのかを確認してみるのが手っ取り早いでしょう。

.ml-* と .mr-* の名前を .ms-* と .me-* に変更しました。
.pl-* と .pr-* の名前を .ps-* と .pe-* に変更しました。
.text-left と .text-right の名前を .text-start と .text-end に変更しました。
リンクは、特定のコンポーネントの一部でない限り、デフォルトで（ホバー時だけでなく）下線が引かれます。

地味に、リンク（ a タグ）の下線有無のデフォルトが正反対になるのは見た目の影響がありましたね。

Hugoへの組み込み方

さて、Bootstrap 5 そのものの解説はCSSへの理解が深いプロフェッショナルにお任せするとして、ここでは Hugo へどのように組み込んだのかの一例を解説します。

組み込み方法の選択肢

Hugo においては、大まかには以下の方法が選択肢になります。

Bootstrap を配信している外部サイト（CDN）を直接読み込む
- 最も手軽で殆どのケースでは望ましい使い方でしょう
- https://getbootstrap.com/docs/5.2/getting-started/download/#cdn-via-jsdelivr
.css ファイルと .js ファイルをそのまま配置する
- 定番のサイト構築方法
npm コマンドによる Bootstrap ライブラリのインストール
- npm コマンドの利用環境がある場合にはお手軽。Hugo を利用するユーザー層であれば使っている可能性も高め
gohugoio/hugo-mod-bootstrap-scss: Packages Bootstrap SCSS (v4 and v5) as a Hugo Module
- Hugo が備える hugo mod コマンドによりインストールする

3番の Hugo Module を利用したほうが Hugo らしさがありますが、JavaScript ファイルの準備に一手間加わっているほか、今後の Bootstrap バージョンアップの際に不都合が生じる可能性もあるので、シンプルに2番の npm によるインストールとします。以降の記載は npm が前提となります。

本記事での組み込み方

当然、これはサイトの要件あるいは製作者の管理方法など好みによりますので、誰しもに当てはまる方法ではありません。一つの選択肢として参照してください。

npm (package.json) を用いて bootstrap をダウンロードする
node_modules 配下にあるファイルを Hugo で読み込む

Bootstrap のセットアップには

ここで記載する手順は、Bootstrap のバージョン 5.2 の時期における解説となります。

参照サイト

Get started with Bootstrap

Bootstrap is a powerful, feature-packed frontend toolkit. Build anything窶杷rom prototype to production窶琶n minutes.

By getbootstrap.com

面倒な手順を利用する動機

CDNあるいはビルド済みファイルを利用すればあっという間ですが、ひと手間加えることで以下のメリットがあります。

必要なファイル（コンポーネント）のみを読み込めばいいので配信ファイルサイズを小さくできる
JavaScript の処理時間が減ることで PageSpeed Insights でのスコアが向上する（かもしれない）

NPM でのインストール

ここでは npm コマンドによりインストールしていますが、Bootstrap のライブラリをどのように取得するかだけであり、サイトから zip 形式で取得するでも構いません。 npm のセットアップの方がマウスでの操作が少ないので気楽に利用します。

npm insatll bootstrap

// package.json の中身（部分抜粋）
{
  "dependencies": {
    "bootstrap": "^5.2.2"
  }
}

CSSファイルの配置

Hugo でサイト作りをしている場合、 assets ディレクトリ配下に SCSS ファイルを配置してビルドしているケースが多いと思います。そのため、SCSSファイル（ここでは main.scss とします）から node_modules/ 配下の Boostrap ソースファイルを import する形としています。

.
├── assets/
    ├── scss/
        ├── main.scss

├── node_modules/
    ├── bootstrap/
        ├── scss/

具体的なコードは以下の通り（ main.scss ）

// @import を記載するファイルからの相対パスで指定するので ../ の数は利用状況による
@import "../../../node_modules/bootstrap/scss/bootstrap";

SCSSでのインポートに関する具体的な記載例は Bootstrap 5.2 の Importing セクションに記載があります。

公式の手段は「Option A: Include all of Bootstrap」「Option B: Include parts of Bootstrap」の2通りが記載されていますが、Option B の必要部品だけを読み込む形のほうが最終的なCSSファイルサイズを削減できるので、少しでもファイルサイズを小さくしたい場合は考えてみることも有益です。しかし、どの部品を使いたいか定まっていない場合は、うまく動作しない場合の切り分けが面倒になるので素直にすべてのファイルを読み込む Option A がよいでしょう。

SCSS (CSS) ファイルの準備はこれだけで完了です。

JavaScript ファイルの配置

JavaScript の場合は SCSS のように import して完了、と単純にはいきません。これは前述3番の手順（Hugo Module側）の index.js や、Bootstrap 本体のビルド用スクリプトにあるようにESMやらトランスパイル等の事情を挟むためですが、JavaScript 界隈の複雑な事情には明るくないため素直にビルドされた後の bootstrap.bundle.js を利用することにします。

具体的には、 node_modules 配下の dist/js/ にあるファイルを選びます。そこには見慣れたファイルがいくつかありますので、必要なものを手動で assets/にコピーしてください。

.
├── assets/
    ├── vendor/
        ├── bootstrap-5.2.bundle.js

├── node_modules/
    ├── bootstrap/
        ├── dist/
            ├── js/
                ├── bootstrap.bundle.js
        ├── scss/

assets 配下のディレクトリ構成は好みですが、ここでは vendor ディレクトリに Bootstrap の JavaScript ファイルを配置しています。

ファイルの操作方法

ここまで説明した CSS および JavaScript の操作方法いずれも、Hugo の基本知識があることを前提に一分説明を省略していますが補足すると以下のとおりです。

Assets 配下においてしまえば、通常の Assets Bundling の手順に準じます。
あるいは Resources.Get などの関数を利用したくない場合は、 Static ディレクトリ ( static/ ) に配置してしまえば Hugo のテンプレート関数を利用する必要もなく、HTMLの知識そのもので構築できます。

(参考) JavaScript ファイルも node_modules から import したい

JavaScript は SCSS のように import して完了しないと書きましたが、正確には正しい説明ではありません。JavaScript を module形式 (ESM) として読み込む <script type="module"> の記載をするか、あるいはトランスパイルするなどの手段が考えられます。

Internet Explorer のサポートが終了したことで現役のモダンブラウザであれば不自由なく ESM が使えるようですし移行してしまうのも一案ではありますが、Bootstrap 以外にも様々なライブラリを利用している場合は管理が面倒くさくなるかもしれません（特に Assets Bundling にて1ファイルにしている場合）。

トランスパイルについては、Hugo そのものにも Babel トランスパイルする機能が備わっていますので (*1)、試行錯誤すれば解決することもできると思われますが、解決したい対象が Bootstrap だけであれば手間とコストの都合で微妙な選択肢だと感じます。（技術的関心としてはあるのですけどね）

上記の理由から、JavaScript ファイルは公式にバンドルされたものをそのまま配置する形で現状落ち着いています。