Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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');
+ });
+});