docs: clickable sidebar headers, fix casing, and keep groups open (opensearch-project#105)

- Add custom Sidebar component with clickable group headers for
  Agent Health, Evaluations, Traces, and Configuration
- Hide index pages from sidebar via sidebar.hidden frontmatter
- Fix lowercase group labels (evaluations -> Evaluations, etc.)
- Keep parent groups open when navigating to child pages

Signed-off-by: Megha Goyal <goyamegh@amazon.com>

Author: goyamegh

docs/starlight-docs/astro.config.mjs

@@ -33,6 +33,7 @@ export default defineConfig({
 			components: {
 				Header: './src/components/CustomHeader.astro',
 				PageSidebar: './src/components/PageSidebar.astro',
+				Sidebar: './src/components/Sidebar.astro',
 			},
 			sidebar: [
 				{

docs/starlight-docs/src/components/Sidebar.astro

@@ -0,0 +1,78 @@
+---
+import Default from '@astrojs/starlight/components/Sidebar.astro';
+
+// Map of sidebar group labels to their display name and index page URL.
+// Keys match the rendered label text; displayName fixes casing if needed.
+const groupLinks: Record<string, { displayName: string; href: string }> = {
+	'Agent Health': { displayName: 'Agent Health', href: '/docs/agent-health/' },
+	'evaluations': { displayName: 'Evaluations', href: '/docs/agent-health/evaluations/' },
+	'traces': { displayName: 'Traces', href: '/docs/agent-health/traces/' },
+	'configuration': { displayName: 'Configuration', href: '/docs/agent-health/configuration/' },
+};
+---
+
+<div data-group-links={JSON.stringify(groupLinks)}>
+	<Default><slot /></Default>
+</div>
+
+<script>
+	function makeGroupHeadersClickable() {
+		const container = document.querySelector('[data-group-links]');
+		if (!container) return;
+		const groupLinks: Record<string, { displayName: string; href: string }> = JSON.parse(
+			container.getAttribute('data-group-links') || '{}'
+		);
+
+		const groups = document.querySelectorAll('nav.sidebar details');
+		for (const group of groups) {
+			const summary = group.querySelector('summary');
+			const label = summary?.querySelector('.group-label .large') as HTMLElement | null;
+			if (!summary || !label) continue;
+
+			const labelText = label.textContent?.trim() ?? '';
+			if (!(labelText in groupLinks)) continue;
+
+			const { displayName, href } = groupLinks[labelText];
+
+			const anchor = document.createElement('a');
+			anchor.href = href;
+			anchor.textContent = displayName;
+			anchor.className = 'group-header-link';
+
+			const isCurrentPage =
+				window.location.pathname === href ||
+				window.location.pathname === href.replace(/\/$/, '');
+
+			const isChildPage = window.location.pathname.startsWith(href);
+
+			if (isCurrentPage) {
+				anchor.setAttribute('aria-current', 'page');
+			}
+
+			// Open this group and all ancestors if we're on this page
+			// or any child page within this section
+			if (isCurrentPage || isChildPage) {
+				let el: HTMLElement | null = group as HTMLElement;
+				while (el) {
+					if (el.tagName === 'DETAILS') (el as HTMLDetailsElement).open = true;
+					el = el.parentElement;
+				}
+			}
+
+			label.textContent = '';
+			label.appendChild(anchor);
+
+			// When clicking the link: prevent the summary toggle, keep it open, navigate
+			summary.addEventListener('click', (e) => {
+				if ((e.target as HTMLElement).closest('.group-header-link')) {
+					e.preventDefault();
+					(group as HTMLDetailsElement).open = true;
+					window.location.href = anchor.href;
+				}
+			});
+		}
+	}
+
+	makeGroupHeadersClickable();
+	document.addEventListener('astro:after-swap', makeGroupHeadersClickable);
+</script>

docs/starlight-docs/src/content/docs/agent-health/configuration/index.md

@@ -2,7 +2,7 @@
 title: "Configuration"
 description: "Configure Agent Health to connect your AI agent, set up storage, and customize evaluation behavior"
 sidebar:
-  order: 7
+  hidden: true
 ---
 
 Agent Health works out of the box with demo data and file-based storage. Configure it when you're ready to connect your own agent or use production services.

docs/starlight-docs/src/content/docs/agent-health/evaluations/index.md

@@ -2,7 +2,7 @@
 title: "Evaluations"
 description: "How Agent Health evaluates AI agents using Golden Path trajectory comparison and LLM judges"
 sidebar:
-  order: 3
+  hidden: true
 ---
 
 Agent Health evaluates AI agents by comparing their execution trajectories against expected outcomes using an LLM judge. This page explains the evaluation pipeline and core concepts.

docs/starlight-docs/src/content/docs/agent-health/index.md

@@ -2,8 +2,7 @@
 title: "Agent Health"
 description: "Evaluation and observability framework for AI agents with Golden Path trajectory comparison"
 sidebar:
-  label: "Overview"
-  order: 1
+  hidden: true
 ---
 
 Agent Health is an evaluation and observability framework for AI agents. It helps you measure agent performance through "Golden Path" trajectory comparison — where an LLM judge evaluates agent actions against expected outcomes. Check out the [GitHub repository](https://github.com/opensearch-project/agent-health) for source code and contributions.

docs/starlight-docs/src/content/docs/agent-health/traces/index.md

@@ -2,7 +2,7 @@
 title: "Trace Visualization"
 description: "Real-time trace monitoring and comparison for AI agent executions in Agent Health"
 sidebar:
-  order: 6
+  hidden: true
 ---
 
 Agent Health provides built-in trace visualization for monitoring and debugging AI agent executions. If your agent emits OpenTelemetry traces, Agent Health can display them alongside evaluation results.

docs/starlight-docs/src/styles/custom.css

@@ -14,3 +14,16 @@
 .sl-markdown-content .icon-card-list li {
   margin: 0 !important;
 }
+
+/* Clickable sidebar group header links */
+.group-header-link {
+  color: inherit;
+  text-decoration: none;
+}
+.group-header-link:hover {
+  text-decoration: underline;
+  color: var(--sl-color-text-accent);
+}
+.group-header-link[aria-current='page'] {
+  color: var(--sl-color-text-accent);
+}