Hugoでマニュアルを作る #6 メンテナンス — 検索インデックス、アクセシビリティ、ドキュメント文化

フレームワーク Hugo Documentation Static Site

2026年6月7日日曜日

読了 4分

#5 まで来ると、多言語とバージョンまで備えたドキュメントになります。これで作る段階は終わりました。ドキュメントは一度作って終わりではなく、製品と共に育ち続けるものです。最終回では、そのドキュメントを長く生かしておく運用を扱います。

今回のシリーズは Hugoでマニュアルを作る の全6回です。

#1 インストールから最初のドキュメントまで
#2 サイドバーと検索 — ドキュメントの情報構造を整える
#3 コンテンツ作成 — コードブロック、Mermaid、コールアウト
#4 Cloudflare Pages でデプロイしてドメインを接続する
#5 多言語とバージョン管理
#6 メンテナンス — 検索インデックス、アクセシビリティ、ドキュメント文化 ← この記事

この記事では 規模に耐える検索、みんなのためのアクセシビリティ、ドキュメントを生かす文化 の三つを整理します。

規模に耐える検索 — Pagefind #

#2 で Hextra の内蔵検索を接続しました。ドキュメントが数百編に増えると、ビルド時に作ったインデックスを一度にダウンロードする方式は、最初のローディングを重くします。このとき乗り換えられるツールが Pagefind です。

Pagefind は Hugo が作った public の成果物を、ビルド 以後に さらって検索インデックスを作ります。インデックスを細かく分割しておき、ブラウザが検索語に必要な断片だけをその都度受け取っていくので、ドキュメントが数千編でも最初のローディングが軽いです。日本語のような言語の分割にも対応しています。ビルドコマンドのあとに一行付ければよいです。

Pagefind で検索インデックスを作る

hugo --gc --minify
npx -y pagefind --site public

検索ボックスは、Pagefind が提供する UI を検索ページに差し込みます。

検索 UI を差し込む

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>
<div id="search"></div>
<script>
  window.addEventListener('DOMContentLoaded', function () {
    new PagefindUI({ element: '#search' });
  });
</script>

みんなのためのアクセシビリティ #

ドキュメントは、できるだけ多くの人が読めるようにすべきです。Hextra は基本のアクセシビリティが良好ですが、記事を書いて整える過程で壊れやすい箇所がいくつかあります。

見出しの階層 を飛ばしません。一段ずつ下りていってこそ、スクリーンリーダーが構造を正しく読みます。

見出しの階層を守る

# ページタイトル (h1, 1ページに一つ)
## 大きな節 (h2)
### 小さな節 (h3)

リンクのテキスト は、それ自体で意味が通じる必要があります。「ここをクリック」ではなく「インストールガイド」のように、行き先を書きます。
画像には代替テキスト を付けます。ダイアグラムを Mermaid で描けばテキストなので、この問題から自由です。
色のコントラスト を守ります。テーマの色をいじるときは、本文と背景のコントラストが WCAG AA 基準(4.5:1)を超えるか確認します。

ドキュメントを生かす文化 #

良いドキュメントツールを備えても、更新が止まればドキュメントはたちまち嘘になります。長く生き続けるドキュメントの共通点は、ツールではなく習慣です。

核心は、#1 で出発点に据えた Docs as Code を最後まで守ることです。ドキュメントをコードと同じリポジトリに置き、機能を変える Pull Request の中で関連ドキュメントも一緒に直します。「ドキュメント更新」を作業完了の条件に入れれば、コードとドキュメントが別々に動く事態が減ります。

これに加え、実用的な工夫をいくつか紹介します。記事ごとに所有者と最終更新日を見せて古い記事を見つけやすくし、壊れたリンクはビルド段階で自動で点検し、大きな改編を先延ばしにするより小さく頻繁に直します。完璧な一度の整備よりも、地道な小さな更新がドキュメントを生かします。

シリーズを締めくくって #

六編にわたって、Hugo と Hextra でドキュメントサイトを最初から運用まで作りました。インストールし(#1)、サイドバーと検索で構造を整え(#2)、コードブロックとダイアグラムで内容を埋め(#3)、Cloudflare Pages でデプロイし(#4)、多言語とバージョンを足し(#5)、最後に長く維持する方法(#6)まで来ました。

ブログが時系列の記事の集まりなら、ドキュメントサイトは構造化されたリファレンスです。その違いが、ツール選択から運用の習慣まですべてを分けました。さあ、皆さんのチームのドキュメントを、この流れの上に乗せてみてください。