画像のメンテナンス

画像はユーザーの理解に役立ちますが、メンテナンスは難しいです。負担を減らすために、次の方針を使っています。

ドキュメントでは、次のような種類の画像をサポートしています。

• ダイアグラム
• スクリーンショット

このうち、検索できて変更しやすいため、Mermaid ダイアグラムを優先します。Mermaid ダイアグラムの更新コストは、スクリーンショットの撮り直しや、デザイナーとダイアグラムを直すよりはるかに低いです。

画像メンテナンスを改善する最善の方法は、画像を使わないことです。

もう 1 つの効率化は、ドキュメントで参照されなくなった画像を削除することです。UI 変更や情報漏洩の監査が必要になったとき、未使用画像まで見なくて済むので特に役立ちます。

これを GitHub Actions の組み合わせで行っています。

未使用画像を検出する専用の GitHub Action があります。未使用画像の検出 ↗。

この GitHub Action の処理は次のとおりです。

1. コンテンツ内のすべての .png または .svg ファイルを探します。
2. それらのファイルがいずれかの MDX ファイルから参照されているかを確認します。
3. 未参照のファイルがある場合、GitHub issue ↗ を作成します。

未使用画像の検出 と合わせて、ビルドプロセス ↗ にも画像パスを検証するロジックがあります。

export default defineConfig({
	site: "https://developers.cloudflare.com",
	markdown: {
		smartypants: false,
		remarkPlugins: [remarkValidateImages],
		rehypePlugins: [
			rehypeMermaid,
			rehypeExternalLinks,
			rehypeHeadingSlugs,
			rehypeAutolinkHeadings,
			// @ts-expect-error plugins types are outdated but functional
			rehypeTitleFigure,
			rehypeShiftHeadings,
		],
	},

これにより、ビルド時の nimbus/image-ref lint ルールがすべての画像パスを検証します。パスが存在しない場合はエラーを投げ、サイトのビルドを止めます。

未使用画像の検出 と組み合わせると、テクニカルライターはプルリクエストで未使用ファイルを安全に削除できます。サイトが正しくビルドできていれば、どこからも参照されていない画像ファイルだけを削除したことになります。