feat(KNO-7916): Add support for linking to Accordion components

[rachael-t]

Description

Our docs rely heavily on the Accordion component to collapse content for better scannability. Currently, when we need to link to a specific accordion (rather than just the nearest heading), we can't - we can only link to a section. In pages with lots of accordions, like Setting Channel Data, this means users land on the right section but still have to hunt for the right accordion themselves.

For example, in the MS Teams overview, we link to the channel data docs for MS Teams-specific requirements but we can't deep-link directly to that accordion, so users have to find it manually.

What this PR does
Adds an optional anchorId prop to the Accordion component. When set, it assigns that value as the wrapper's DOM id and automatically opens the accordion on page load if the URL hash matches. Note that this is optional and accordions without anchorId should behave exactly as before (so there's no requirement to add it everywhere). Also, each anchorId must be unique within a page, but the same value can be reused across pages.

In this PR, I've only added anchorId to the specific example described above.

Open questions for the team

1. Should we do a broader audit to add anchorId across the docs, or just add them as we notice they'd be useful? My take is that we don't need it on every accordion but rather only where we have a stable deep link that should open a specific one. If an accordion is unlikely to be linked to directly, a heading anchor is probably enough. But open to other opinions!
2. Does the approach I've taken with Accordion make the most sense? I'm very open to other opinions here as well!

Tasks

KNO-7916

Recordings

Current behavior

Screen.Recording.2026-04-10.at.10.38.12.AM.mov

New behavior
https://docs-git-rt-kno-7916-linking-to-accordions-knocklabs.vercel.app/integrations/chat/microsoft-teams/overview#how-to-set-channel-data-for-a-microsoft-teams-integration-in-knock

Screen.Recording.2026-04-10.at.10.39.24.AM.mov

[linear]

KNO-7916 [Docs] Support deep links that open a specific Accordion

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Apr 29, 2026 2:53pm

[cursor]

Risk HIGH: Adds an optional anchorId prop to the shared Accordion component to support deep-linking via URL hash fragments, with two MDX files updated to use it.

Reasons

• A .tsx file in components/ is modified (components/ui/Accordion.tsx), which automatically triggers HIGH risk per classification rules
• The Accordion component is a shared/reusable UI component used across many documentation pages
• A new React hook (useLayoutEffect) and a global event listener (hashchange) are introduced, changing component behavior
• The change is backward-compatible (the anchorId prop is optional and existing accordions are unaffected)
• The MDX changes are minimal (link URL update + adding the new anchorId prop to one accordion instance)

Notes

• Verify that useLayoutEffect does not cause SSR hydration warnings since getHashFragment() returns "" on the server but may return a value on the client. Consider whether useEffect would be more appropriate to avoid potential hydration mismatches.
• Confirm that the hashchange event listener is cleaned up correctly on unmount and that multiple accordions with different anchorId values on the same page do not conflict.
• Check that the deep-link behavior works correctly when navigating between pages in the Next.js SPA (client-side routing may not fire hashchange in all cases).
• The id attribute set on the Box element should be verified to not collide with any existing heading anchor IDs on the same page.

  

_{Sent by Cursor Automation: Docs PR classifier}

[scotidodson]

Should we do a broader audit to add anchorId across the docs, or just add them as we notice they'd be useful? My take is that we don't need it on every accordion but rather only where we have a stable deep link that should open a specific one. If an accordion is unlikely to be linked to directly, a heading anchor is probably enough. But open to other opinions!
I think a broad update would be beneficial so we don't end up doing a bunch of one-off changes, but I don't think the need is urgent. Maybe we could take a step back and see if there's anything else we want to broadly address related to FAQ sections (since those are the most common use case) so we can do that at the same time. E.g., normalizing writing style of the Qs.

Does the approach I've taken with Accordion make the most sense? I'm very open to other opinions here as well!
Makes sense to me, but it'd be great to get a glance from Jeff in case he has any suggestions for handling it differently.

[scotidodson]

I think it could be worthwhile to add a helper to ensure this string is properly formatted for the URL. I know from your example that we intend to supply the hyphenated slug, but could see that being missed during usage. Alternatively, maybe altering the param name to anchorSlug helps reinforce the expectation?

[rachael-t]

I like that suggestion - anchorSlug feels more helpful!

[scotidodson]

While testing the link to this I noticed that we don't totally scroll this open accordion into view. I assume what's happening is we're calculating the height before the accordion is open, and it seems like that might be a common issue with accordion element UX.

I tested locally and confirmed this concern will mostly be relevant to FAQ sections or the rare non-FAQ accordion at the bottom of the page like this. That doesn't really help except to suggest there may be something hacky to be done to indicate a scroll to bottom.

If we want to address this, I'd be fine with holding it as a follow up improvement.

[rachael-t]

Interesting - I noticed it a little bit while working on this (I think because as you mentioned, it's at the bottom of the page) but it feels much worse now (directs you much higher on the page). 🤔

[rachael-t]

@scotidodson FYI that I added the anchorSlug for the tenant-specific preference merge hierarhcy (since I mentioned it yesterday and for another example to view/test): https://docs-git-rt-kno-7916-linking-to-accordions-knocklabs.vercel.app/multi-tenancy/per-tenant-preferences#tenant-preference-evaluation-rules

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 55e2afa. Configure here.}