SEO, metadata, and AIO optimization policy

Decision

• Prohibit ad-hoc per-page metadata output and centralize head generation in a shared layer (dedicated head responsibility under Layout).
• Ensure indexable pages never have contradictions across title, description, canonical, hreflang, and og:url.
• Make Open Graph and Twitter metadata mandatory for shareable pages, with absolute image URLs.
• Use noindex only for pages intentionally excluded from search results, aligned with sitemap inclusion rules.
• For AIO (AI Overview and similar systems), avoid hacks and focus on high-quality primary content plus valid structured data.

Required metadata fields and rules

canonical / hreflang operation

• Emit hreflang only for translations that actually exist.
• Use default-locale (ja) representative URL for x-default.
• Do not emit hreflang for untranslated locales.
• Each localized page must canonicalize to itself (no cross-locale canonicalization).

OGP / Twitter cards

• The following are mandatory for shareable pages:
  • og:type (website or article by page type)
  • og:title
  • og:description
  • og:url
  • og:image (absolute URL)
  • og:image:alt
  • twitter:card (summary_large_image)
  • twitter:title
  • twitter:description
  • twitter:image
• Use /brand/og.jpg as the site-wide fallback image when a page does not provide a dedicated social image (the actual file will be added in a follow-up task).

noindex / sitemap alignment

• Pages with noindex: true must emit meta robots as noindex,nofollow and be excluded from sitemap output.
• Keep X-Robots-Tag: noindex for non-production hosts such as workers.dev.
• Keep draft and noindex as distinct meanings:
  • draft: not publishable yet
  • noindex: published but intentionally excluded from search results

Structured data (core for AIO readiness)

• Keep existing Person and BreadcrumbList.
• Add page-type structured data:
  • Detail pages (blog, release notes, ADR): Article (or TechArticle when appropriate)
  • Index pages (changelog, tools, etc.): CollectionPage
  • About page: ProfilePage
• JSON-LD must reflect only rendered facts; do not include fabricated ratings, numbers, or claims.

Content principles for AIO reuse

• Do not add hidden AI-only text. Place a concise, high-signal intro near the top of each page.
• Keep heading hierarchy valid and prefer one main topic per page.
• Make definitions and procedures self-contained instead of relying on external context.

Context

Current implementation already covers title, description, canonical, and hreflang to some extent, but the following remain inconsistent or missing:

• Unified Open Graph and Twitter output policy
• Operational rules connecting noindex and sitemap generation
• Structured data policy by page type
• Shared content criteria that work for both search snippets and AI-generated summaries

Given the current multilingual architecture (ja as default locale, other locales as path prefixes), we need a single policy that improves machine readability without breaking existing routing.

Options

• Option A: Continue page-by-page metadata customization
• Option B: Keep only minimal tags (title/description/canonical)
• Option C: Define and enforce a shared metadata + structured data policy (chosen)

Rationale

• Consistency: Prevent canonical/hreflang/og:url mismatch.
• Operational safety: Reduce missing-tag regressions on new pages.
• Reusability: Make one source of truth reusable for search, social cards, and AI summaries.
• Extensibility: Enable phased rollout of social image automation and metadata checks.

Consequences

• Implementation work is required to introduce a shared SEO head responsibility (or expand current Layout responsibilities).
• Content Collection schemas need consistent SEO fields (ogImage, noindex, etc.).
• CI checks should detect missing required tags, canonical-hreflang inconsistencies, and noindex pages leaking into sitemap.
• Success criteria:
  • 100% required metadata coverage on indexable pages
  • 100% canonical and og:url parity
  • 0 structured-data validation errors