fix: broken Data Pipeline link and Send Data sidebar labels (opensearch-project#99)

kylehounslow · web-flow · commit 5edcd0c426d9 · 2026-03-18T09:36:21.000-07:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -826,6 +826,42 @@ helm uninstall observability-stack-test
 - Provide both quick start and detailed explanations
 - Include troubleshooting sections
 
+### Docs Site Development Workflow
+
+The docs site is built with [Starlight](https://starlight.astro.build/) (Astro). Source files are in `docs/starlight-docs/`.
+
+**Required workflow for all docs changes:**
+
+1. **Build** — validates internal links via `starlight-links-validator` plugin. The build will fail if any internal links are broken. Never skip this step.
+   ```bash
+   cd docs/starlight-docs && npm install && npm run build
+   ```
+
+2. **Preview** — start a local preview server and visually verify changes.
+   ```bash
+   bash docs/starlight-docs/test/preview.sh          # start server
+   # Open http://localhost:4321/docs in browser
+   bash docs/starlight-docs/test/preview.sh --stop    # stop server
+   ```
+
+3. **Rebuild after changes** — if you make further edits, rebuild before previewing:
+   ```bash
+   bash docs/starlight-docs/test/preview.sh --stop
+   bash docs/starlight-docs/test/preview.sh --build
+   bash docs/starlight-docs/test/preview.sh
+   ```
+
+**Critical rules:**
+- **Never start the astro server directly** (e.g. `npx astro preview`, `nohup`, `npm run preview`). Always use `test/preview.sh` — it handles background process management correctly. Direct invocations will block the terminal.
+- **Always build before previewing.** The link validator only runs during build. Previewing without building first will show stale output.
+- **Never use `grep -P` (Perl regex)** — macOS does not support it. Use `sed` or `grep -E` instead.
+- **Verify the server is responding** after starting preview by checking `curl -s http://localhost:4321/docs` returns 200 before telling the user it's ready.
+
+**Sidebar configuration:**
+- Sidebar labels and ordering are configured in `docs/starlight-docs/astro.config.mjs` — this is the single source of truth.
+- **Do not use frontmatter `sidebar.label` or `sidebar.order` to control group/section headings.** Frontmatter only controls individual page labels, not the group name shown in the sidebar for a directory. Use explicit `items` with `label` in `astro.config.mjs` instead (see "Send Data" and "Get Started" sections as examples).
+- Sections using `autogenerate` derive group labels from directory names (lowercase). Replace `autogenerate` with explicit `items` when proper casing or custom ordering is needed.
+
 ### Icons
 
 Use OpenSearch UI (OUI) icons for documentation components. Browse the full set at https://oui.opensearch.org/1.23/#/display/icons. SVG sources are at https://github.com/opensearch-project/oui/tree/main/src/components/icon/assets. Prefer 32x32 icons over 16x16 for consistent sizing.
diff --git a/docs/starlight-docs/astro.config.mjs b/docs/starlight-docs/astro.config.mjs
@@ -2,6 +2,7 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import mermaid from 'astro-mermaid';
+import starlightLinksValidator from 'starlight-links-validator';
 
 // https://astro.build/config
 export default defineConfig({
@@ -16,6 +17,9 @@ export default defineConfig({
 		}),
 		starlight({
 			title: 'OpenSearch - Observability Stack',
+			plugins: [starlightLinksValidator({
+				errorOnLocalLinks: false,
+			})],
 			logo: {
 				src: './src/assets/opensearch-logo-darkmode.svg',
 			},
@@ -54,7 +58,25 @@ export default defineConfig({
 				{
 					label: 'Send Data',
 					collapsed: true,
-					autogenerate: { directory: 'send-data' },
+					items: [
+						{ label: 'Overview', link: '/send-data/' },
+						{
+							label: 'OpenTelemetry',
+							autogenerate: { directory: 'send-data/opentelemetry' },
+						},
+						{
+							label: 'Applications',
+							autogenerate: { directory: 'send-data/applications' },
+						},
+						{
+							label: 'Infrastructure',
+							autogenerate: { directory: 'send-data/infrastructure' },
+						},
+						{
+							label: 'Data Pipeline',
+							autogenerate: { directory: 'send-data/data-pipeline' },
+						},
+					],
 				},
 				{
 					label: 'Investigate',
diff --git a/docs/starlight-docs/package-lock.json b/docs/starlight-docs/package-lock.json
diff --git a/docs/starlight-docs/package.json b/docs/starlight-docs/package.json
@@ -14,6 +14,7 @@
     "astro": "^5.6.1",
     "astro-mermaid": "^1.3.1",
     "mermaid": "^11.12.3",
-    "sharp": "^0.34.2"
+    "sharp": "^0.34.2",
+    "starlight-links-validator": "^0.19.2"
   }
 }
diff --git a/docs/starlight-docs/src/content/docs/get-started/installation.mdx b/docs/starlight-docs/src/content/docs/get-started/installation.mdx
@@ -103,4 +103,4 @@ To fully remove, delete the repository directory.
 
 - [Platform Overview](/docs/get-started/overview/) — architecture and data flow
 - [Core Concepts](/docs/get-started/core-concepts/) — key terms and ideas
-- [Quickstart](/docs/get-started/quickstart/) — send your first traces
+- [Quickstart](/docs/get-started/quickstart/first-traces/) — send your first traces
diff --git a/docs/starlight-docs/src/content/docs/index.mdx b/docs/starlight-docs/src/content/docs/index.mdx
@@ -23,7 +23,7 @@ OpenSearch Observability Stack is an **open-source, OpenTelemetry-native observa
 ## Quickstarts
 
 <LinkCard title="Install & Explore" href="/docs/get-started/installation/" description="Install the stack and explore traces already flowing from the built-in example services." />
-<LinkCard title="Send Your First Traces" href="/docs/get-started/quickstart/" description="Instrument an app with OpenTelemetry and see traces in dashboards." />
+<LinkCard title="Send Your First Traces" href="/docs/get-started/quickstart/first-traces/" description="Instrument an app with OpenTelemetry and see traces in dashboards." />
 <LinkCard title="Trace an AI Agent" href="/docs/ai-observability/agent-tracing/" description="Instrument an AI agent with GenAI semantic conventions and visualize the execution graph." />
 
 <Aside type="tip">
@@ -41,4 +41,4 @@ The stack optionally ships with [example services](https://github.com/opensearch
 ## Community
 
 - [GitHub](https://github.com/opensearch-project/observability-stack) — issues, PRs, and discussions
-- [Contributing guide](/docs/contributing/) — how to contribute
+- [Contributing guide](https://github.com/opensearch-project/observability-stack/blob/main/CONTRIBUTING.md) — how to contribute
diff --git a/docs/starlight-docs/src/content/docs/sdks/index.md b/docs/starlight-docs/src/content/docs/sdks/index.md
@@ -41,6 +41,6 @@ The SDK configures a `BatchSpanProcessor` that exports in the background — you
 
 ## Related links
 
-- [Agent Traces](/docs/apm/agent-traces/) — viewing traces in OpenSearch Dashboards
+- [Agent Traces](/docs/investigate/discover-traces/) — viewing traces in OpenSearch Dashboards
 - [Send Data](/docs/send-data/) — OTLP pipeline setup and collector configuration
 - [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) — the OTel spec the SDKs follow
diff --git a/docs/starlight-docs/src/content/docs/sdks/javascript.md b/docs/starlight-docs/src/content/docs/sdks/javascript.md
@@ -259,7 +259,7 @@ register({ autoInstrument: false });
 ## Related links
 
 - [Python SDK](/docs/sdks/python/) — Python equivalent
-- [Agent Traces](/docs/apm/agent-traces/) — viewing traces in OpenSearch Dashboards
+- [Agent Traces](/docs/investigate/discover-traces/) — viewing traces in OpenSearch Dashboards
 - [Send Data](/docs/send-data/) — OTLP pipeline and collector setup
 - [FAQ](/docs/sdks/faq/) — common questions
 - [npm](https://www.npmjs.com/package/opensearch-genai-sdk) — package page
diff --git a/docs/starlight-docs/src/content/docs/sdks/python.mdx b/docs/starlight-docs/src/content/docs/sdks/python.mdx
@@ -428,7 +428,7 @@ register(auto_instrument=False)
 ## Related links
 
 - [JavaScript SDK](/docs/sdks/javascript/) — TypeScript/Node.js equivalent
-- [Agent Traces](/docs/apm/agent-traces/) — viewing traces in OpenSearch Dashboards
+- [Agent Traces](/docs/investigate/discover-traces/) — viewing traces in OpenSearch Dashboards
 - [Send Data](/docs/send-data/) — OTLP pipeline and collector setup
 - [FAQ](/docs/sdks/faq/) — common questions
 - [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) — OTel spec reference
diff --git a/docs/starlight-docs/src/content/docs/send-data/applications/python.md b/docs/starlight-docs/src/content/docs/send-data/applications/python.md
@@ -264,6 +264,6 @@ with tracer.start_as_current_span("llm.chat") as span:
 - [Applications overview](/docs/send-data/applications/)
 - [Auto-instrumentation](/docs/send-data/opentelemetry/auto-instrumentation/)
 - [Manual instrumentation](/docs/send-data/opentelemetry/manual-instrumentation/)
-- [Agent traces](/docs/apm/agent-traces/)
+- [Agent traces](/docs/investigate/discover-traces/)
 - [OpenTelemetry Python documentation](https://opentelemetry.io/docs/languages/python/) -- Official OTel Python SDK reference
 - [Python instrumentation libraries](https://opentelemetry.io/ecosystem/registry/?language=python&component=instrumentation) -- Available auto-instrumentation packages
diff --git a/docs/starlight-docs/src/content/docs/send-data/data-pipeline/data-prepper.md b/docs/starlight-docs/src/content/docs/send-data/data-pipeline/data-prepper.md
@@ -7,7 +7,7 @@ Data Prepper is the pipeline engine that receives OTLP telemetry, routes events
 
 ## Prerequisites
 
-- OpenSearch Observability Stack running (see [Quickstart](/docs/get-started/quickstart/))
+- OpenSearch Observability Stack running (see [Quickstart](/docs/get-started/quickstart/first-traces/))
 - OTel Collector configured to export to Data Prepper on port 21890
 
 ## Pipeline configuration
diff --git a/docs/starlight-docs/src/content/docs/send-data/index.md b/docs/starlight-docs/src/content/docs/send-data/index.md
@@ -52,14 +52,14 @@ Core instrumentation framework. Learn about the OTel Collector configuration, au
 
 Language-specific guides for instrumenting your services. Covers Python, Java, Node.js, Go, .NET, and browser applications, plus dedicated guidance for AI/LLM agent observability.
 
-### [Data Pipeline](/docs/send-data/pipeline/)
-
-Configure the backend processing layer. Covers Data Prepper pipelines for trace and log processing, Prometheus for metrics storage, and index management in OpenSearch.
-
 ### [Infrastructure](/docs/send-data/infrastructure/)
 
 Collect telemetry from your infrastructure. Covers host metrics, container monitoring, Kubernetes observability, and cloud provider integrations.
 
+### [Data Pipeline](/docs/send-data/data-pipeline/)
+
+Configure the backend processing layer. Covers Data Prepper pipelines for trace and log processing, Prometheus for metrics storage, and index management in OpenSearch.
+
 ## Quick Start
 
 To start sending data from any application, set two environment variables and run with auto-instrumentation:
@@ -73,6 +73,6 @@ Then follow the language-specific guide in the [Applications](/docs/send-data/ap
 
 ## Related Links
 
-- [Get Started](/docs/get-started/) -- Platform overview and sandbox setup
+- [Get Started](/docs/get-started/installation/) -- Platform overview and sandbox setup
 - [Investigate](/docs/investigate/) -- Query and explore ingested data
 - [APM](/docs/apm/) -- Application performance monitoring views
diff --git a/docs/starlight-docs/src/content/docs/send-data/infrastructure/index.md b/docs/starlight-docs/src/content/docs/send-data/infrastructure/index.md
@@ -107,7 +107,7 @@ Infrastructure traces are less common but useful for:
 
 Before setting up infrastructure monitoring, ensure you have:
 
-- A running OpenSearch Observability Stack (see [Sandbox](/docs/get-started/sandbox/))
+- A running OpenSearch Observability Stack (see [Sandbox](/docs/get-started/installation/))
 - Network access from your infrastructure to the OTel Collector endpoints (ports 4317/4318)
 - Appropriate permissions to deploy agents on your target infrastructure
 
diff --git a/docs/starlight-docs/src/content/docs/send-data/opentelemetry/collector.md b/docs/starlight-docs/src/content/docs/send-data/opentelemetry/collector.md
diff --git a/docs/starlight-docs/test/preview.sh b/docs/starlight-docs/test/preview.sh

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@`
`14`	`14`	`"astro": "^5.6.1",`
`15`	`15`	`"astro-mermaid": "^1.3.1",`
`16`	`16`	`"mermaid": "^11.12.3",`
`17`		`- "sharp": "^0.34.2"`
	`17`	`+ "sharp": "^0.34.2",`
	`18`	`+ "starlight-links-validator": "^0.19.2"`
`18`	`19`	`}`
`19`	`20`	`}`