SPEC

ET-453 — Custom Docs Sidebar (mirror home)

Source of truth for the ET-453 sidebar work. Linear: ET-453 (descoped remainder of ET-420). Approach chosen by Ross: custom docs sidebar that mirrors the home .hc-sidebar (not restyling the native Mintlify sidebar — that approach was attempted and parked, see git show et-453-parked-restyle).

Scope (the 4 ET-453 items)

#	Item	Status / plan
①	Collapse/expand top-level categories in left sidebar	This spec. Replace native #sidebar content on doc pages with a custom .hc-nav mirroring the home sidebar (collapsible groups).
②	Article header redesign (breadcrumb + title + read-time + last-updated)	Breadcrumb piece here (.fp-breadcrumb); read-time/last-updated + dark-mode handled by ET-506 (PR #110). Full header polish builds on ET-506 after merge.
③	Don’t auto-navigate when a folder is clicked	Free with this approach: group headers are <button> (toggle only, no href).
④	FieldPulse (footer) logo blank-white-screen	Already fixed by ET-502 (commit b6c1f02, image-zoom disabled on [data-rmiz]). Verify on ET-502 preview; no change here.

Why custom-injected (not native restyle)

The parked attempt (et-453-parked-restyle, f01b560) restyled the native Mintlify sidebar and was abandoned: “the native Mintlify sidebar resists pixel-level parity with the custom .hc-sidebar (link colors, chevron color, exact spacing).” We instead inject our own markup (the .hc-nav-group structure that already has perfect CSS) so we own the structure and inherit home parity for free.

Design

On doc pages only (not landing body:has(.hc-landing-hero), not changelog):

1. docs-sidebar.js (new, content root → auto-included on every page):

   • Locates #sidebar, injects a .hc-docs-nav containing a .hc-sidebar-search-trigger + .hc-nav with .hc-nav-group blocks built from the NAV data below (mirrors index.mdx).
   • Adds hc-docs-sidebar-active class to #sidebar → CSS hides the native nav content.
   • Marks the active page’s .hc-nav-topic (aria-current="page") and auto-expands its group; others follow the home defaults (Integrations collapsed).
   • Idempotent (“already injected” guard) + MutationObserver to survive Mintlify SPA re-renders/navigation.
   • Collapse toggling is already handled by landing-nav.js (delegated click on .hc-nav-group-header toggles .collapsed) and the search trigger (.hc-sidebar-search-trigger) — no duplication.

2. styles.css additions:

   • #sidebar.hc-docs-sidebar-active > div:not(.hc-docs-nav) { display:none !important } — hide native content.
   • .hc-docs-nav layout inside #sidebar (padding, full-height scroll) reusing existing .hc-nav-* rules.
   • .fp-breadcrumb (article eyebrow) — reuse parked styling.

3. Article reachability (IA): since articles are not in the visible sidebar, every article must remain reachable from its category card grid. Reuse the parked foundation: scripts/generate-category-cards.mjs (+~105 cards) and article-breadcrumb.js (+ .fp-breadcrumb). Cherry-pick from et-453-parked-restyle where sound; re-verify all links resolve (scripts/validate-nav.ts, mint).

NAV data (mirror of index.mdx .hc-sidebar)

• Getting Started: General /core-platform/general-ui-ux, Customers /core-platform/customers, Scheduling /core-platform/scheduling, Invoices & Estimates /core-platform/invoices-estimates, User Management /core-platform/user-management
• Using FieldPulse: Jobs, Projects, Inventory, Reporting, Purchase Orders, Custom Workflows, Commission & Profitability, Booking Portal, Contracts & Signatures, Dynamic Proposals, Templates, Time Sheets, Assets, Material Lists, Maintenance Agreements, Messaging
• Features & Add-Ons: Engage, FP Payments, Pricebook, Custom Forms, Payments, ClearPath, Operator AI
• Accounting: QuickBooks Online, QuickBooks Desktop, Xero, MYOB
• Integrations (collapsed by default): Reece (US), Reece maX (ANZ), Other Integrations

DRY note: this duplicates index.mdx’s sidebar data. Acceptable for now; a future pass could extract a shared JSON both consume.

QA plan

• mint dev from this worktree; Playwright (channel:'chrome', waitUntil:'domcontentloaded').
• Visual parity: doc-page sidebar vs home .hc-sidebar (light + dark) — confirm with Ross before IA work.
• Behavior: collapse/expand toggles; group header never navigates (③); active page highlighted + its group expanded.
• Survives client-side navigation (click a link, sidebar persists/re-injects).
• Responsive (mobile drawer) + dark mode.
• All article links resolve from card grids; breadcrumb present on article pages.
• Evidence → .qa/ET-453/.

Non-goals / risks

• Not removing the footer-nav doc-nav block (separate concern).
• Risk: SPA re-render wiping injection → mitigated by MutationObserver + CSS-based native hide.
• Risk: #sidebar internal scroll/positioning — verify scroll works with injected flow content.