unlisted フィールド導入と 3 段階可視性モデルの確立
背景
現状 schema には可視性制御フィールドとして draft と noindex が存在するが、以下の問題があった:
noindexの責務が「クローラ除外」と「一覧除外」に暗黙で混在しがち- 「一覧には出したくないが URL は生きていて欲しい」ケース(プライバシーポリシー等の page 系)に対応するフィールドがない
draftの文言「一覧・詳細から除外」は「ビルド除外」と読めるが、実装挙動と乖離している可能性がある
type: page のような規約系ドキュメントは、記事一覧のノイズになる一方でフッター等から常時リンクされる。この UX 要件を素直に表現するフィールドが不在だった。
決定
以下2点を決定する。
1. unlisted フィールドを追加する
意味論:
- ビルドはされる(詳細ページは生成される)
- サイト内の一覧・RSS から除外される
- URL 直打ちで到達可能
- meta robots は通常(クローラは通す。SEO 影響なし)
- サイドバーの「非表示を表示」トグルで一覧にも表示できる
noindex との違い:
noindexは SEO 制御(外部クローラ向け)unlistedはサイト内導線制御(自サイトの一覧向け)- 両者は直交し、独立して指定可能
2. 3 段階可視性モデルを確立する
| フィールド | ビルド | 一覧(通常) | 一覧(表示トグルON) | 直接URL | SEO |
|---|---|---|---|---|---|
draft: true | ✗ | ✗ | ✗ | 404 | ─ |
unlisted: true | ✓ | ✗ | ✓ | ✓ | 通常 |
noindex: true | ✓ | ✓ | ✓ | ✓ | noindex |
//2026-09-23:
さんざん考えて結局こうなった。慣例が決まっていなかったり、語彙が似ているとLLMのハルシネーションが強く出る。
フィールド ビルド → 直接URL 一覧(通常) 一覧(トグルON)& wikiリンク解決 RSS sitemap meta robots Pagefind nobuild: true✗(404) ─ ─ ─ ─ ─ ─ nolist: true✓ ✗ ✗ ✗ ✗ noindex ✗ unlisted: true✓ ✗ ✓ ✓ ✓ 通常 ✓ noindex: true✓ ✓ ✓ ✓ ✗ noindex ✗ 全て false / 省略 ✓ ✓ ✓ ✓ ✓ 通常 ✓
派生効果:
unlisted: true→ 一覧・RSS・タグ集計から除外、sitemap には含めるnoindex: true→ meta robots noindex、sitemap から除外、一覧には影響しないdraft: true→getStaticPathsから除外、ビルド対象外
3. type: page の慣習
type: page の記事は原則 unlisted: true を frontmatter に明示的に書く。
- schema 側で type 依存のデフォルト値は持たない(フラット構造原則を維持)
- あくまで運用慣習として明示記述する
- 「一覧に出したい page」がある場合は
unlisted: falseを明示、または省略
却下案
案A: noindex に一覧除外の責務を統合
却下理由:
- 意味論が直交する2機能を1フィールドに詰めると、4象限のうち中間2つが表現不能
- 「一覧には出したいがクローラは避けたい」等が書けなくなる
案B: hidden / private という命名
却下理由:
hiddenは「非表示」が広義すぎ、URL アクセスも隠れる印象privateは認証必須の印象があり実態と乖離unlistedは YouTube 由来で「限定公開」概念が広く認知されている
案C: type: page に対して schema でデフォルト unlisted=true
却下理由:
- 「完全フラット構造」「type 非依存」原則に反する
- 明示性が失われ、記事を見た時に unlisted 状態が frontmatter から読めなくなる
- 慣習として運用者が明示記述する方が、schema の単純性と可読性を両立できる
影響範囲
schema
docs/SCHEMA.mdにunlistedフィールドを追加noindexの説明を「SEO 純化」に修正draftの説明を「ビルド対象外」に明確化- 可視性マトリクス表を追加
実装
src/content.config.ts: zod schema にunlisted: z.boolean().optional()を追加src/lib/entries.ts:NormalizedEntryにunlistedを派生値として追加(data.unlisted ?? false)- 一覧取得ヘルパーで
unlisted除外フィルタを実装(例:getListedEntries()) - RSS 生成で
unlistedを除外 - sitemap 生成で
noindexのみ除外(unlistedは含める) - サイドバーに「非表示を表示」トグル UI を追加(localStorage で状態保持)
既存記事
type: pageの全記事にunlisted: trueを追記する移行作業
draft の挙動確定
- 別途、現状のビルド挙動を検証し、schema 文言と一致していなければ実装修正する
- 本 ADR のスコープ外だが、関連タスクとして記録
検証
pnpm build後、dist/にunlisted記事の HTML が生成されていること- 一覧ページに
unlisted記事が表示されないこと - URL 直打ちで到達できること
- サイドバートグル ON で一覧に表示されること
- RSS に含まれないこと
- sitemap には含まれること
- meta robots が通常であること
補足
3 段階可視性モデルは以下のユースケースを網羅する:
| ユースケース | 設定 |
|---|---|
| 執筆中の下書き | draft: true |
| プライバシーポリシー等の規約 | unlisted: true |
| URL 共有限定の告知記事 | unlisted: true |
| 内輪向けメモ(検索避け) | unlisted: true, noindex: true |
| 検索避けだが一覧には出す | noindex: true |
| 通常記事 | 全て省略 |