Search And Discovery designed
Search should help readers answer "where do I start?" and "which source backs this?" The first implementation should be internal and generated from portal metadata, not a hosted public search dependency.
The first reader-facing index is Discovery Index.
Decision
Use a generated local discovery index first. Defer Algolia/DocSearch until the portal has an approved external publication track.
| Option | Fit now | Use later |
|---|---|---|
| Generated local index | Best for internal review, no external service, can include owner/status/source metadata | Keep as source of truth for filters and review packs |
| Algolia/DocSearch | Premature while the portal is internal and visibility tracks are not filtered | Candidate for public/customer/partner docs after publication filtering exists |
| Static navigation only | Already useful, but insufficient once deep dives and API pages grow | Keep as the primary curated path, not the only discovery model |
Discovery Index Shape
Each indexed portal page should expose:
| Field | Why it matters |
|---|---|
title, slug, description | Basic result display |
audience, visibility, status | Audience and publication filtering |
owner, review_domain | Maintainer and reviewer routing |
last_reviewed, review_cadence, freshness_risk | Staleness and sync triage |
source_docs | Traceability back to canonical docs |
| headings | Section-level discovery inside long pages |
| diagram count / diagram labels | Visual inventory and review-pack assembly |
| generated references | API, AsyncAPI, source inventory, and future playground surfaces |
Reader Workflows
Implementation Direction
- Extend the existing source inventory into a portal-page discovery index.
- Add a reader-facing discovery page with filters for audience, status, owner, review domain, source doc, and freshness risk.
- Add heading extraction so long pages are searchable at section level.
- Add diagram inventory from Mermaid blocks and static image assets.
- Use the same index for review packs and publication-track readiness.
- Revisit hosted search after public/customer/partner filtering is real.
Guard Direction
The checker should eventually validate that:
- every indexed page has the required portal metadata,
- every result links to a valid route,
- source-doc links exist,
- generated API artifacts are present,
- stale high-risk pages are visible in the index,
- internal-only pages do not appear in external-track indexes.