docs(nav): menulinks nav, flat doc search corpus, breadcrumbs, quick search, and cache TTLs

[jdcmsd]

Okay, it's ready for some testing. I didn't want to merge it straightaway because it became MUCH more voluminous than I'd intended, and I've learned the hard way not to do a launch on a Friday night.

This completely redoes the breadcrumb system, retiring the last vestiges of the ancient 7-layer docs relationship structure. It's still technically in the contentlets; it just no longer plays a role in site organization. Breadcrumbs are the most obvious place where its removal will be noticed; it's also no longer playing any kind of determinate role in the quick search results.

This makes me very happy, to have flattened and horizontalized the latter, because now removing "stub" articles that just existed as section parents will no longer have any implications for the content previously held hostage below it.

This also integrates with the Menu Link API plugin I made, to replace the use of the Nav API. This allows me to reference menu links irrespective of their showOnMenu status, which allows me to split the nav in a way that complements the nav/search compromise. That is, now the nav consists of a "daylight nav" that's always there, and a "shadow nav" that shoehorns docs into the nav when you're visiting them, even if they're not usually part of the curated list.

My hope is that this improves on one of the pain points of the last few months in a meaningful way.

---

Claude summary of the technical fiddly bits below.

---

This PR finishes moving docs navigation off the deep GraphQL TOC and onto menulinks, while keeping a flat GraphQL DotcmsDocumentation list for quick search, sitemap, and legacy sideNav[0].dotcmsdocumentationchildren consumers.

Navigation & data

• Left nav and mobile docs chrome use getNavSections / fetchNavData (menulinks API + navPayloadToApiNavTree), with filterApiNavForMenuAndSlug unchanged for visible menu behavior.
• Return a second tree from getNavSections: sectionsAllForPaths from filterApiNavKeepAllLeaves so quick-search result cards can show breadcrumb trails for showOnMenu: false links without exposing them in the filtered nav. Threaded through docs layout, block pages, persona landings, header, and client refetch.
• getSideNav now queries a flat DotcmsDocumentationCollection (non-zero limit, valid sortBy), synthetic root shape preserved for callers; cache key bumped through docsSearchFlatV4 as the query evolved.

Breadcrumbs

• Single Breadcrumbs.tsx implementation (removed duplicate .js resolution bug); menulinks forest uses neutral children via navSectionsToBreadcrumbForest.
• Trail segments are plain text; home link defaults to /; path matching uses canonical slug rules where appropriate.

Quick search

• Corpus = merged menulinks-derived rows + CMS flat list with explicit merge so sparse GraphQL rows do not wipe menulinks seoDescription / tags; separate title vs navTitle; headline helper in the overlay; whitespace normalization + multi-token scoring fallback.
• Menulink slug → parentPath map for breadcrumb line in results (full tree for paths).

Caching

• DOCS_SIDE_NAV_CACHE_TTL_SECONDS centralizes TTL for the flat docs GraphQL response and navCache payload (15 minutes).
• navCache default stdTTL aligned to 900s; menulinks navCache / fetchNavData paths already used ~15m-style TTLs.

Other

• RedesignedNavTree uses shared transformApiResponseToNavSections from navTransform; invalid DotcmsDocumentation.modDate sort string avoided (modDate desc only).

Suggested checks

• Docs page: left nav, mobile nav, quick search (on- and off-menu slugs), breadcrumbs.
• Block page + persona pages that pass nav props.
• llms.txt still builds from filtered sections only.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
new-new-devsite	Ready	Preview, Comment	May 4, 2026 11:54pm