学び・改修記録

項目	内容
文書番号	LN-001
更新日	2026-06-12
記録	Claude Code（実装担当）

構築・運用で踏んだハマりと回避策を時系列で記録する。同じ穴に二度落ちないための文書。形式は「事象 → 原因 → 回避策」。

2026-06-12 構築時

npm init の生成値はそのまま使えない

事象：npm init -y の生成した package.json が "type": "commonjs" で、VitePress の設定ファイル（ESM 形式）と噛み合わない
原因：npm のデフォルトが ESM でない
回避策："type": "module" に書き換え、スクリプト（docs:dev / docs:build / docs:preview）も手で定義した

サイドバー自動生成は「各章フォルダに index.md」が前提

事象：index.md を持たないフォルダは生のフォルダ名（02-design）が章名として表示され、さらに並び順がタイトルの文字列ソートになって番号順（00→07）が崩れた
原因：vitepress-sidebar の useFolderTitleFromIndexFile は index.md があるフォルダにしか効かない。また sortMenusByName は表示テキスト（日本語タイトル）でソートするため、番号プレフィックスが無視される
回避策：①各章フォルダに必ず index.md（章トップ）を置く運用に統一、②ソートを sortMenusOrderNumericallyFromLink: true（リンク URL の数値でソート）に変更。以後、章を増やすときは「フォルダ + index.md」がセット

公開デプロイの所要時間はほぼアップロード

事象：ビルドは 1.3 秒なのに、初回デプロイ全体は約 110 秒かかった
原因：静的サイト一式（65 ファイル）の初回アップロードに時間がかかる。2 回目以降は差分のみで短縮される
回避策：特に不要（既知の挙動として記録）。「ビルドが遅い」と誤診しないこと

2026-06-12 レイアウト総点検時

タスクリスト記法（`- [ ]`）は素の VitePress では描画されない

事象：リリース計画書のチェックリストが「[ ]」という文字のまま表示されていた
原因：チェックボックス描画の拡張が VitePress 標準では無効
回避策：チェックリストは共通クラス .ap-checklist で表現（装飾は読み口側に寄せる原則どおり、md 記法に依存しない）

表のセルは日本語が1文字ずつ縦に折れる

事象：課題管理表（7列）で「優先度」「未着手」が1文字1行に縦割れしていた
原因：日本語はどの文字間でも改行できるため、列幅が狭くなると文字単位で折り返される
回避策：テーマ CSS で見出しセルを折り返し禁止（nowrap）、本文セルを単語単位の改行（keep-all）に統一

ヒーロー文言がフォントサイズ依存で中折れする

事象：トップの「プロジェクト資産ポータル」が「ポータ／ル」の位置で折れていた
原因：規定の見出しサイズ（56px）では10文字が1行に収まらない
回避策：テーマ CSS でPC幅のみ 48px に調整し、語中改行を禁止（keep-all）。スマホ幅は自然な折り返しに任せる

変更履歴

版	日付	変更内容
1.0	2026-06-12	初版作成
1.1	2026-06-12	構築中のハマり2件（サイドバー前提・デプロイ時間）を追記
1.2	2026-06-12	レイアウト総点検のハマり3件（タスクリスト非対応・表の縦割れ・ヒーロー中折れ）を追記