decisiondecided

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)直接URLSEO
draft: true✗✗✗404─
unlisted: true✓✗✓✓通常
noindex: true✓✓✓✓noindex

//2026-09-23:
さんざん考えて結局こうなった。慣例が決まっていなかったり、語彙が似ているとLLMのハルシネーションが強く出る。

フィールドビルド → 直接URL一覧(通常)一覧(トグルON)& wikiリンク解決RSSsitemapmeta robotsPagefind
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
通常記事全て省略