Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: emit docs_sidebar_click with sidebar group and depth
Kshitij Jhunjhunwalafe623da4348a
diff --git a/docs/app/(home)/docs/layout.tsx b/docs/app/(home)/docs/layout.tsxindex daee4cbc9..ea2e3b5a2 100644--- a/docs/app/(home)/docs/layout.tsx+++ b/docs/app/(home)/docs/layout.tsx@@ -1,6 +1,8 @@import { source } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';import { decorateSidebarBadges } from '@/lib/decorate-sidebar-badges';+import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';+import { SidebarAnalytics } from '@/components/sidebar-analytics';interface BadgeFrontmatter {experimental?: boolean;@@ -16,6 +18,7 @@ const newUrls = new Set();const tree = decorateSidebarBadges(source.pageTree, experimentalUrls, newUrls);+const navIndex = buildSidebarNavIndex(tree);export default function Layout({ children }: LayoutProps<'/docs'>) {return (@@ -26,6 +29,7 @@ export default function Layout({ children }: LayoutProps<'/docs'>) {themeSwitch={{ enabled: false }}searchToggle={{ enabled: false }}>+ <SidebarAnalytics index={navIndex} />{children}</DocsLayout>);diff --git a/docs/app/(home)/reference/(v31)/layout.tsx b/docs/app/(home)/reference/(v31)/layout.tsxindex eba3a8560..cb42b31f6 100644--- a/docs/app/(home)/reference/(v31)/layout.tsx+++ b/docs/app/(home)/reference/(v31)/layout.tsx@@ -2,6 +2,8 @@ import { getReferenceSource } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';import { prepareTree } from '@/lib/filter-api-version';+import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';+import { SidebarAnalytics } from '@/components/sidebar-analytics';export default async function Layout({ children }: { children: ReactNode }) {const source = await getReferenceSource();@@ -29,6 +31,7 @@ export default async function Layout({ children }: { children: ReactNode }) {sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}>+ <SidebarAnalytics index={buildSidebarNavIndex(pageTree)} />{children}</DocsLayout>);diff --git a/docs/app/(home)/reference/v3/layout.tsx b/docs/app/(home)/reference/v3/layout.tsxindex aa9f48866..465afe415 100644--- a/docs/app/(home)/reference/v3/layout.tsx+++ b/docs/app/(home)/reference/v3/layout.tsx@@ -2,6 +2,8 @@ import { getReferenceSource } from '@/lib/source';import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';import { prepareTree } from '@/lib/filter-api-version';+import { buildSidebarNavIndex } from '@/lib/sidebar-nav-index';+import { SidebarAnalytics } from '@/components/sidebar-analytics';export default async function Layout({ children }: { children: ReactNode }) {const source = await getReferenceSource();@@ -15,6 +17,7 @@ export default async function Layout({ children }: { children: ReactNode }) {sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}>+ <SidebarAnalytics index={buildSidebarNavIndex(tree)} />{children}</DocsLayout>);diff --git a/docs/components/sidebar-analytics.tsx b/docs/components/sidebar-analytics.tsxnew file mode 100644index 000000000..4c2fc3c13--- /dev/null+++ b/docs/components/sidebar-analytics.tsx@@ -0,0 +1,61 @@+'use client';++import { useEffect } from 'react';+import { usePostHog } from 'posthog-js/react';+import type { SidebarNavIndex } from '@/lib/sidebar-nav-index';++/**+ * Emits `docs_sidebar_click` for sidebar navigation.+ *+ * One delegated listener rather than per-link handlers, and the group/folder/+ * depth come from `index` (built from the page tree) rather than from walking+ * the rendered DOM. An href that is not in the index emits nothing — a guessed+ * group is worse than a missing event.+ */+export function SidebarAnalytics({ index }: { index: SidebarNavIndex }) {+ const posthog = usePostHog();++ useEffect(() => {+ if (!posthog) return;++ function handleClick(event: MouseEvent) {+ const target = event.target;+ if (!(target instanceof Element)) return;++ const anchor = target.closest('a[href]');+ // The desktop and mobile sidebar containers. Matching `aside` instead+ // would also catch the Ask AI panel, whose answers link to docs pages.+ // These two ids are the same hooks `app/global.css` styles against.+ if (!anchor || !anchor.closest('#nd-sidebar, #nd-sidebar-mobile')) return;++ const href = anchor.getAttribute('href');+ if (!href) return;++ let url: URL;+ try {+ url = new URL(href, window.location.href);+ } catch {+ return;+ }+ if (url.origin !== window.location.origin) return;++ const pathname = url.pathname.replace(/\/$/, '') || '/';+ const entry = index[pathname];+ if (!entry) return;++ posthog.capture('docs_sidebar_click', {+ href: pathname,+ group: entry.group,+ folder: entry.folder,+ depth: entry.depth,+ position: entry.position,+ from_path: window.location.pathname,+ });+ }++ document.addEventListener('click', handleClick, true);+ return () => document.removeEventListener('click', handleClick, true);+ }, [index, posthog]);++ return null;+}diff --git a/docs/lib/create-docs-layout.tsx b/docs/lib/create-docs-layout.tsxindex a81d50ea1..05c07a174 100644--- a/docs/lib/create-docs-layout.tsx+++ b/docs/lib/create-docs-layout.tsx@@ -1,9 +1,13 @@import { DocsLayout } from 'fumadocs-ui/layouts/docs';import type { ReactNode } from 'react';+import { buildSidebarNavIndex } from './sidebar-nav-index';+import { SidebarAnalytics } from '@/components/sidebar-analytics';type Source = typeof import('./source').examplesSource;export function createDocsLayout(source: Source) {+ const navIndex = buildSidebarNavIndex(source.pageTree);+return function Layout({ children }: { children: ReactNode }) {return (<DocsLayout@@ -13,6 +17,7 @@ export function createDocsLayout(source: Source) {sidebar={{ collapsible: false, footer: null, tabs: false }}themeSwitch={{ enabled: false }}>+ <SidebarAnalytics index={navIndex} />{children}</DocsLayout>);diff --git a/docs/lib/sidebar-nav-index.ts b/docs/lib/sidebar-nav-index.tsnew file mode 100644index 000000000..fe9076126--- /dev/null+++ b/docs/lib/sidebar-nav-index.ts@@ -0,0 +1,84 @@+/**+ * Flattens a fumadocs page tree into a url -> sidebar-position lookup.+ *+ * Analytics needs to know which sidebar group a click came from, and the+ * rendered sidebar cannot answer that: separators render as `<p>` and folders+ * as `<button>`, both fumadocs-internal details that change on upgrade. The+ * tree is the stable source, so the mapping is derived here at build time and+ * the click handler only does an href lookup.+ *+ * Mirrors the traversal in `app/llms.txt/route.ts`.+ */+import type { ReactNode } from 'react';+import type { Root, Node } from 'fumadocs-core/page-tree';++export interface SidebarNavEntry {+ /** Enclosing separator heading, e.g. "Core concepts". */+ group: string | null;+ /** Enclosing folder title, e.g. "Authentication"; null at the top level. */+ folder: string | null;+ /** 1 = top-level row, 2 = folder child, 3 = nested. */+ depth: number;+ /** 1-based position within the group, in top-to-bottom sidebar order. */+ position: number;+}++export type SidebarNavIndex = Record<string, SidebarNavEntry>;++/** Sidebar badges wrap names in elements, so only plain names yield text. */+function nodeText(name: ReactNode): string | null {+ if (typeof name === 'string') return name;+ if (typeof name === 'number') return String(name);+ return null;+}++interface WalkState {+ group: string | null;+ position: number;+}++function walkNodes(+ nodes: Node[],+ folder: string | null,+ depth: number,+ state: WalkState,+ index: SidebarNavIndex+): void {+ for (const node of nodes) {+ if (node.type === 'separator') {+ state.group = nodeText(node.name);+ state.position = 0;+ continue;+ }++ if (node.type === 'page') {+ state.position += 1;+ index[node.url] = { group: state.group, folder, depth, position: state.position };+ continue;+ }++ const folderName = nodeText(node.name) ?? folder;++ // A folder's index page is the folder's own row, so it keeps the folder's depth.+ if (node.index) {+ state.position += 1;+ index[node.index.url] = {+ group: state.group,+ folder: folderName,+ depth,+ position: state.position,+ };+ }++ // A separator nested in a folder must not leak into the folder's siblings.+ const outerGroup = state.group;+ walkNodes(node.children, folderName, depth + 1, state, index);+ state.group = outerGroup;+ }+}++export function buildSidebarNavIndex(tree: Root): SidebarNavIndex {+ const index: SidebarNavIndex = {};+ walkNodes(tree.children, null, 1, { group: null, position: 0 }, index);+ return index;+}diff --git a/docs/tests/static/sidebar-nav-index.test.ts b/docs/tests/static/sidebar-nav-index.test.tsnew file mode 100644index 000000000..750fa0d81--- /dev/null+++ b/docs/tests/static/sidebar-nav-index.test.ts@@ -0,0 +1,81 @@+/**+ * Sidebar nav index tests.+ *+ * Exercises the real docs page tree: `docs_sidebar_click` reports the group,+ * folder and depth from this index, so a traversal bug silently drops pages+ * from analytics rather than breaking the site.+ */+import { describe, expect, test } from 'bun:test';+import { readFile } from 'node:fs/promises';+import { join } from 'node:path';+import { flattenTree } from 'fumadocs-core/page-tree';++import { buildSidebarNavIndex } from '../../lib/sidebar-nav-index';+import { source } from '../../lib/source';++const index = buildSidebarNavIndex(source.pageTree);++describe('buildSidebarNavIndex', () => {+ test('folder children carry their group, folder and depth', () => {+ expect(index['/docs/authentication/white-labeling-authentication']).toEqual({+ group: 'Core concepts',+ folder: 'Authentication',+ depth: 2,+ position: expect.any(Number),+ });++ expect(index['/docs/extending-sessions/shared-connections']).toEqual({+ group: 'Guides',+ folder: 'Extend sessions',+ depth: 2,+ position: expect.any(Number),+ });+ });++ test('top-level pages have no folder', () => {+ expect(index['/docs/quickstart']).toEqual({+ group: 'Get Started',+ folder: null,+ depth: 1,+ position: expect.any(Number),+ });+ });++ test('folder index pages resolve to the folder row', () => {+ expect(index['/docs/authentication']).toEqual({+ group: 'Core concepts',+ folder: 'Authentication',+ depth: 1,+ position: expect.any(Number),+ });+ });++ test('position increases down a group and resets at the next separator', () => {+ expect(index['/docs/quickstart'].position).toBeGreaterThan(index['/docs'].position);+ expect(index['/docs/how-composio-works'].position).toBe(1);+ });++ test('every page in the sidebar tree resolves to a non-null group', () => {+ const missing = flattenTree(source.pageTree.children)+ .map(page => page.url)+ .filter(url => index[url]?.group == null);++ expect(missing).toEqual([]);+ });++ test('every root meta.json entry that is a page is indexed', async () => {+ const meta = JSON.parse(+ await readFile(join(import.meta.dir, '../../content/docs/meta.json'), 'utf-8')+ ) as { pages: string[] };++ const indexed = meta.pages+ .filter(entry => !entry.startsWith('---') && entry !== '...')+ .map(entry => (entry === 'index' ? '/docs' : `/docs/${entry}`))+ .filter(url => index[url] != null);++ // Entries that are folders without an index page have no url of their own.+ expect(indexed).toContain('/docs/quickstart');+ expect(indexed).toContain('/docs/authentication');+ expect(indexed).toContain('/docs/providers');+ });+});