Navbar & Dynamic Menus

The header on matters.ai is composed at runtime by components/nav/Navbar.tsx. It starts from a static seed in menu.config.ts and then enriches three dropdowns with live data fetched from WordPress through internal API routes.

This page documents the full pipeline — how it works, how to publish/rename/hide an item, and the conventions marketing and engineering use to control the result.

1. Pipeline overview#

WordPress (CPT or special category)
        │  posts.title, posts.slug, posts.excerpt
        ▼
Next.js route handler        ── /api/use-cases/nav       (CPT: use_case)
   - fetches list             /api/industries/nav        (CPT: industry)
   - parses excerpt           /api/case-studies/nav      (special category: read_what_matters___case_studies)
   - applies overrides
   - sorts
        │  { items: [{ title, slug, menuOrder }] }
        ▼
Navbar.tsx (client component)
   - mounts with `staticNavigationMenu` (from menu.config.ts)
   - useEffect per source → fetch → merge into the right dropdown
        │
        ▼
Rendered <header>            ┐
                             │  the user sees a hybrid menu — static
                             │  shape + dynamic children pulled live.

Three things matter:

1. The static seed sets the dropdown's shape (label, href of the parent, any always-present children).
2. The route handler decides which WordPress items belong, what their visible label is, and the sort order.
3. The Navbar merge decides where in the static menu the items land — Solutions → By Use Cases, Solutions → By Industries, and Customers.

2. The static seed (menu.config.ts)#

menu.config.ts exports several MenuItem constants and a navigationMenu array that the Navbar renders. Three of those constants get their children replaced (Use Cases, Industries) or appended (Customers) at runtime — their hardcoded children are placeholders or always-present links the static menu still needs.

The Navbar merges live items into SOLUTIONS_MENU.children[0] / children[1] and appends to CUSTOMERS_MENU directly, matched by title.

3. The three nav route handlers#

All three live under app/api/*/nav/route.ts. They follow the same template:

1. Build a fetch() to WordPress, requesting only title, slug, and excerpt.
2. Tag the request ({ next: { revalidate, tags } }) so /api/revalidate can bust it.
3. Map posts → items, parsing the excerpt for directives.
4. Sort by menuOrder (asc; default 999).
5. Return { items: [...] } or, on any error, { items: [] }.

Case studies live under a regular post category (one of the "special categories" prefixed with read_what_matters___), not a custom post type. The route first looks up the category by slug, then queries posts filtered by its id. Use Cases and Industries use real WP custom post types (use_case, industry), so they fetch in a single call.

Authentication for the WordPress fetch differs by route. Industries and case-studies use the shared getWPHeaders() helper (lib/api/wp-headers.ts), which sends Basic auth built from WORDPRESS_USERNAME / WORDPRESS_APP_PASSWORD when those are set. Use-cases builds the same Basic-auth header inline from process.env.WORDPRESS_USERNAME / WORDPRESS_APP_PASSWORD rather than calling the helper. In all cases public posts work without auth; the credentials only matter if a particular post is gated.

The cache TTL is not uniform: use-cases and industries cache for 4 hours (revalidate: 60 * 60 * 4), while case-studies caches for 60 seconds (revalidate: 60). The Navbar fetches over the client, so changes take effect either when the tag is busted (WordPress webhook → /api/revalidate → revalidateTag(...)) or after the route's TTL elapses, whichever comes first. See Content & CMS for the webhook side of the loop.

Response shape#

{
  "items": [
    { "title": "Credit Saison India", "slug": "credit-saison", "menuOrder": 10 },
    { "title": "Groww", "slug": "groww", "menuOrder": 20 }
  ]
}

menuOrder is included in the response for debugging — the Navbar only reads title and slug.

4. Excerpt directives (marketing controls)#

These are typed into the WordPress post's Excerpt field. They are stripped before the title appears anywhere on the site, so they're safe to leave in. The route handler parses them with a regex, applies the rule, and removes the matched fragment before returning the title.

⚠️ Today the directive parser only runs in the case-studies route. Use Cases and Industries only honor [ORDER:n]. Bringing the other two directives over is a one-file change if needed — see "Adding a new dynamic source" below for the template.

[ORDER:n] — sort key#

[ORDER:1]
This is the post excerpt that visitors read…

• Lower n appears first in the dropdown.
• Posts without [ORDER] are sorted to the bottom (999).
• Ties are broken by WordPress' default order (most recent first).

[NAV_HIDE] — exclude from navbar#

[NAV_HIDE]
Excerpt content unchanged…

• The case study still publishes and renders at /case-studies/{slug}.
• It is excluded from the Customers dropdown and the public site's other case-study lists.
• Effect appears next time the cache is busted (typically within seconds after publish, otherwise within ~60s — the case-studies route TTL).

[NAV_TITLE:Display Name] — override the displayed nav label#

[NAV_TITLE:PayU]
Long descriptive case-study title for SEO and the page header.

• Only the navbar dropdown label is replaced.
• The page title, URL, OG meta, and listing-page card all keep the full WP title.
• Use this when the SEO-friendly title is too long to live in a nav dropdown.

Combining directives#

All three directives are independent and can coexist in the same excerpt. Order doesn't matter:

[ORDER:1][NAV_TITLE:PayU]
Reducing data-exfiltration risk at scale: how PayU deployed Matters.AI across…

5. Code-level overrides (engineering control)#

When you need to override what marketing put in WP without round-tripping through them, add an entry to lib/case-study-nav-overrides.ts:

export const CASE_STUDY_NAV_OVERRIDES: Record<string, string | null> = {
  "credit-saison": "Credit Saison India", // rename for the nav only
  "payu-beta": null,                        // hide (same effect as [NAV_HIDE])
};

Precedence — highest first:

1. CASE_STUDY_NAV_OVERRIDES[slug] (null → hide; string → rename)
2. [NAV_HIDE] excerpt directive
3. [NAV_TITLE:...] excerpt directive
4. Cleaned WP post title

Sort order has a code-level layer too. The case-studies route first honors an explicit CASE_STUDY_NAV_ORDER array in lib/case-study-nav-overrides.ts — currently ["credit-saison", "groww", "payu"] — placing any slug listed there in that order, ahead of everything else. Items not in the array fall back to their [ORDER:n] excerpt value (default 999).

6. How the Navbar merges dynamic items in#

components/nav/Navbar.tsx holds the rendered menu in React state, initialized to staticNavigationMenu from menu.config.ts. Three useEffect hooks run after mount, one per source. Each fetches its route, then runs a targeted setNavigationMenu(prev => prev.map(...)) that locates the right dropdown by title and either replaces or appends children.

The Customers dedup guard exists because the static seed (CUSTOMERS_MENU in menu.config.ts) already lists specific case studies — e.g. { title: "Credit Saison India", href: "/case-studies/credit-saison" } and { title: "Groww", href: "/case-studies/groww" }. The runtime append would re-add those same /case-studies/{slug} links from WP, so each would appear twice without the guard. The guard lives in Navbar.tsx's case-studies effect and uses a Set of seen href values.

If any fetch fails, the effect catches silently — that dropdown just shows whatever seed was in place. The site never errors because the navbar is partially broken.

7. Case-study card behavior#

The card component components/blogs/BlogCard.tsx detects whether a post belongs to the case-studies category and hides the author block when it does. This affects every place a card is rendered — the case-studies listing (/case-studies), the "You may also like" rail on case-study detail pages (RecommendedBlogs.tsx), and anywhere else case studies appear in card grids.

Detection uses the existing isUnderCategoryPath(slug, ["case-studies"]) helper from lib/special-categories.ts, so any post tagged under the special category — at any depth — is treated as a case study. The date is still shown.

Rationale: case studies are co-authored by the customer and the matters.ai team; surfacing a single WP author on the card creates confusion and looks editorial rather than commercial.

8. Recipes#

Publish a new case study#

1. In WordPress, create a post. Title and slug as you'd like the page to publish.
2. Assign it to the category Read What Matters – Case Studies (slug read_what_matters___case_studies).
3. Optional: add directives to the Excerpt field:
   • [ORDER:5] to position it in the Customers dropdown.
   • [NAV_TITLE:Short Name] if the page title is too long for nav.
4. Publish. WordPress fires the revalidate webhook; within ~5s the public site reads fresh data.
5. Verify:
   • Page renders at /case-studies/{slug}.
   • Customers dropdown lists it under whatever label the directive (or post title) yielded.
   • Card on /case-studies shows the date but no author byline.

Rename a case study in the navbar only#

Two paths, pick whichever fits the channel:

• Marketing: add [NAV_TITLE:Better Name] to the excerpt.
• Engineering: add "slug": "Better Name" to CASE_STUDY_NAV_OVERRIDES.

The code path wins if both are set.

Hide a case study from the navbar (keep the page)#

• Marketing: add [NAV_HIDE] to the excerpt.
• Engineering: add "slug": null to CASE_STUDY_NAV_OVERRIDES.

The page remains reachable at /case-studies/{slug} and via search; only the navbar dropdown drops it.

Force a refresh#

The Navbar honors each route's cache TTL by default (4 hours for use-cases / industries, ~60s for case-studies). To force a refresh:

• Production: revalidateTag("case-studies") via the webhook or a redeploy.
• Local: restart next dev (the in-memory cache resets on boot).

9. Adding a new dynamic source#

To wire a new CPT or special category into a dropdown:

1. Create the route handler at app/api/{your-source}/nav/route.ts. Copy the case-studies handler verbatim if you need directive support, or the simpler industries handler if you only need [ORDER:n]. Use a distinct tags: ["..."] so revalidation can target it.
2. Decide the merge target. Identify the parent menu in menu.config.ts by title, and whether you're replacing children (like Use Cases / Industries) or appending them (like Customers). Pick one strategy and stick with it — mixed merges are fragile.
3. Add the Navbar effect. Mirror the existing useEffects in Navbar.tsx. Match the menu by title, run a setNavigationMenu(prev => prev.map(...)) that mutates only the targeted subtree.
4. Hook into revalidation. Update the WordPress webhook side (lib/cache/revalidation.ts) so edits to the new content type bust your new tag.
5. Document the directives. Each handler that parses directives owns that contract. Update this page when you add or change directive semantics.

10. File map#

11. Failure modes#

12. Why this design#

• WordPress is the source of truth for marketing content, including which case studies exist. We don't want engineering deploys to publish a customer story.
• The static seed exists because some dropdown items are framework links (Customers overview, the Solutions parent itself) that should never depend on WP being reachable.
• Excerpt directives are how we hand marketing surgical control without giving them a CMS field per behavior. The excerpt is already a "comments to the editor" field and supports arbitrary plain text.
• Code overrides exist for the case where marketing's choice can't be honored — e.g. legal asks us to take a customer name out of the navbar urgently but the WP edit pipeline is slow. They are explicit, reviewed, and version-controlled.
• The author-hide on case-study cards mirrors how cards already specialize on category for other things (badge color, listing URL). The behavior is centralized in BlogCard so every surface inherits it.