From a9adbe7271ad61d71121c4d3ef260cdd4d23fdde Mon Sep 17 00:00:00 2001
From: davidfowl <95136+davidfowl@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:08:14 +0000
Subject: [PATCH 1/3] Fix broken Dashboard landing anchors and relative docs
links
The links validator skips relative links and can't see hrefs passed through
JSX expression props, so these broke silently on every locale:
- dashboard/index.mdx: #traces, #structured-logs and #metrics anchors now
target the existing #*-page headings on /dashboard/explore/.
- aspire-dashboard-run.mdx: Dashboard configuration resolved to
/reference/dashboard/configuration/ (404).
- azure-cache-redis-host.mdx: Redis Hosting integration resolved to
/integrations/cloud/caching/redis/redis-host/ (404) with a misspelled anchor.
Add a unit test that resolves expression-prop hrefs and ./ ../ relative links
in the English docs to existing pages and headings.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../src/content/docs/dashboard/index.mdx | 10 +-
.../azure-cache-redis-host.mdx | 2 +-
.../cli/commands/aspire-dashboard-run.mdx | 2 +-
.../unit/docs-internal-links.vitest.test.ts | 142 ++++++++++++++++++
4 files changed, 149 insertions(+), 7 deletions(-)
create mode 100644 src/frontend/tests/unit/docs-internal-links.vitest.test.ts
diff --git a/src/frontend/src/content/docs/dashboard/index.mdx b/src/frontend/src/content/docs/dashboard/index.mdx
index 98e117f2bf..fb296ecf8f 100644
--- a/src/frontend/src/content/docs/dashboard/index.mdx
+++ b/src/frontend/src/content/docs/dashboard/index.mdx
@@ -63,7 +63,7 @@ The Aspire Dashboard is your command center during development. Powered by [Open
lightImage={tracesImageLight}
imageAlt="Aspire Dashboard trace detail view showing a distributed request waterfall with span-level timing and attributes."
imagePosition="left"
- cta={{ label: 'Learn about tracing', href: '/dashboard/explore/#traces' }}
+ cta={{ label: 'Learn about tracing', href: '/dashboard/explore/#traces-page' }}
/>
@@ -139,21 +139,21 @@ Open the dashboard URL, then point your apps' OTLP exporter to `http://localhost
title: 'Distributed tracing',
description:
'Follow requests across service boundaries with span-level detail. Identify bottlenecks and errors instantly.',
- href: '/dashboard/explore/#traces',
+ href: '/dashboard/explore/#traces-page',
},
{
icon: 'document',
title: 'Structured & console logs',
description:
'View structured and console logs from every resource with powerful filtering, search, and error highlighting.',
- href: '/dashboard/explore/#structured-logs',
+ href: '/dashboard/explore/#structured-logs-page',
},
{
icon: 'bars',
title: 'Metrics & monitoring',
description:
'Track request counts, error rates, and custom metrics with interactive charts and exemplar linking.',
- href: '/dashboard/explore/#metrics',
+ href: '/dashboard/explore/#metrics-page',
},
{
icon: 'open-book',
diff --git a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx
index 81582acbe3..6ccde21f11 100644
--- a/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx
+++ b/src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx
@@ -166,7 +166,7 @@ await builder.build().run();
The preceding code pulls the [`docker.io/library/redis`](https://hub.docker.com/_/redis/) container image and runs it locally. The consuming app connects to the container using a password-based connection string during development.
:::tip
-The `RunAsContainer` method accepts an optional delegate that lets you customize the underlying `RedisResource` — for example, adding [Redis Insight](https://redis.io/insight/), [Redis Commander](https://joeferner.github.io/redis-commander/), a data volume, or a data bind mount. For more information, see [Redis Hosting integration](../../../caching/redis/redis-host/#add-redis-resource-with-redis-insights).
+The `RunAsContainer` method accepts an optional delegate that lets you customize the underlying `RedisResource` — for example, adding [Redis Insight](https://redis.io/insight/), [Redis Commander](https://joeferner.github.io/redis-commander/), a data volume, or a data bind mount. For more information, see [Redis Hosting integration](/integrations/caching/redis/redis-host/#add-redis-resource-with-redis-insight).
:::
## Connect to an existing Azure Cache for Redis instance
diff --git a/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx
index 647ab093b5..9eaeaee9fc 100644
--- a/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx
+++ b/src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx
@@ -95,4 +95,4 @@ The following options are available:
## See also
- [aspire dashboard command](../aspire-dashboard/)
-- [Dashboard configuration](../../../dashboard/configuration/)
+- [Dashboard configuration](/dashboard/configuration/)
diff --git a/src/frontend/tests/unit/docs-internal-links.vitest.test.ts b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
new file mode 100644
index 0000000000..350cd85f47
--- /dev/null
+++ b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
@@ -0,0 +1,142 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import GithubSlugger from 'github-slugger';
+import { describe, expect, it } from 'vitest';
+
+// starlight-links-validator only checks Markdown links and string `href` attributes. It
+// skips relative links (`errorOnRelativeLinks: false`) and can't see hrefs passed through
+// JSX expression props such as `cta={{ href: '...' }}` or `capabilities={[{ href: '...' }]}`.
+// This test covers those two gaps for the English docs, which every locale falls back to.
+
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const docsDir = path.join(root, 'src', 'content', 'docs');
+const localeDirs = new Set([
+ 'da',
+ 'de',
+ 'es',
+ 'fr',
+ 'hi',
+ 'id',
+ 'it',
+ 'ja',
+ 'ko',
+ 'pt-br',
+ 'ru',
+ 'tr',
+ 'uk',
+ 'zh-cn',
+]);
+// Excluded by the links validator config and covered by dedicated API reference/Dev Hub tests.
+const skippedPrefixes = ['/reference/api/', '/hub/'];
+
+const collectDocs = (directory: string): string[] =>
+ readdirSync(directory).flatMap((entry) => {
+ const fullPath = path.join(directory, entry);
+ if (statSync(fullPath).isDirectory()) {
+ return directory === docsDir && localeDirs.has(entry) ? [] : collectDocs(fullPath);
+ }
+ return /\.mdx?$/.test(entry) ? [fullPath] : [];
+ });
+
+const routeOf = (file: string) => {
+ const slug = path
+ .relative(docsDir, file)
+ .split(path.sep)
+ .join('/')
+ .replace(/\.mdx?$/, '')
+ .replace(/(^|\/)index$/, '');
+ return slug ? `/${slug}/` : '/';
+};
+
+// Code fences are often indented inside and lists, so track them line by line.
+const stripCodeFences = (source: string) => {
+ let fence: string | undefined;
+ return source
+ .split('\n')
+ .filter((line) => {
+ const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
+ if (fence) {
+ if (
+ marker &&
+ marker[0] === fence[0] &&
+ marker.length >= fence.length &&
+ line.trim() === marker
+ )
+ fence = undefined;
+ return false;
+ }
+ if (marker) {
+ fence = marker;
+ return false;
+ }
+ return true;
+ })
+ .join('\n');
+};
+
+const docs = collectDocs(docsDir);
+const docsByRoute = new Map(docs.map((file) => [routeOf(file), file]));
+const anchorCache = new Map>();
+
+const anchorsOf = (file: string) => {
+ let anchors = anchorCache.get(file);
+ if (!anchors) {
+ const slugger = new GithubSlugger();
+ const source = stripCodeFences(readFileSync(file, 'utf8'));
+ anchors = new Set();
+ for (const [, heading] of source.matchAll(/^#{2,6}\s+(.+?)\s*$/gm)) {
+ const customId = heading.match(/\{#([^}]+)\}$/)?.[1];
+ if (customId) anchors.add(customId);
+ const text = heading
+ .replace(/\{#[^}]+\}$/, '')
+ .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+ .replace(/<[^>]+>/g, '')
+ .replace(/[`*_]/g, '')
+ .trim();
+ anchors.add(slugger.slug(text));
+ }
+ for (const [, id] of source.matchAll(/\bid=["']([^"']+)["']/g)) anchors.add(id);
+ anchorCache.set(file, anchors);
+ }
+ return anchors;
+};
+
+const findBrokenLinks = (file: string) => {
+ const source = stripCodeFences(readFileSync(file, 'utf8'));
+ const route = routeOf(file);
+ const links = [
+ ...[...source.matchAll(/\bhref:\s*['"]([^'"]+)['"]/g)].map(([, href]) => href),
+ ...[...source.matchAll(/\]\((\.{1,2}\/[^)\s]*)\)/g)].map(([, href]) => href),
+ ];
+ const problems: string[] = [];
+ for (const href of links) {
+ if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//')) continue;
+ const [target, anchor] = href.split('#');
+ const pathname = new URL(target, `https://aspire.dev${route}`).pathname;
+ if (
+ skippedPrefixes.some((prefix) => pathname.startsWith(prefix)) ||
+ /\.[a-z0-9]+$/i.test(pathname)
+ )
+ continue;
+ const destination = docsByRoute.get(pathname.endsWith('/') ? pathname : `${pathname}/`);
+ const source = path.relative(docsDir, file).split(path.sep).join('/');
+ if (!destination) {
+ problems.push(`${source}: ${href} resolves to missing page ${pathname}`);
+ } else if (anchor && !anchorsOf(destination).has(anchor)) {
+ problems.push(`${source}: ${href} points to a missing heading #${anchor}`);
+ }
+ }
+ return problems;
+};
+
+describe('English docs internal links not covered by starlight-links-validator', () => {
+ it('finds the English docs', () => {
+ expect(docsByRoute.get('/dashboard/explore/')).toBeDefined();
+ expect(docs.length).toBeGreaterThan(100);
+ });
+
+ it('resolves expression-prop hrefs and relative links to existing pages and headings', () => {
+ expect(docs.flatMap(findBrokenLinks)).toEqual([]);
+ });
+});
From 85711641983c35c523797e5cbacfbbb791ccac31 Mon Sep 17 00:00:00 2001
From: davidfowl <95136+davidfowl@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:19:05 +0000
Subject: [PATCH 2/3] Strip stray angle brackets when slugging headings in the
links test
Addresses the CodeQL incomplete multi-character sanitization alert. The slug
is unchanged because github-slugger already drops < and >.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
src/frontend/tests/unit/docs-internal-links.vitest.test.ts | 1 +
1 file changed, 1 insertion(+)
diff --git a/src/frontend/tests/unit/docs-internal-links.vitest.test.ts b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
index 350cd85f47..024484cc3e 100644
--- a/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
+++ b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
@@ -92,6 +92,7 @@ const anchorsOf = (file: string) => {
.replace(/\{#[^}]+\}$/, '')
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
.replace(/<[^>]+>/g, '')
+ .replace(/[<>]/g, '')
.replace(/[`*_]/g, '')
.trim();
anchors.add(slugger.slug(text));
From ded956c3f4366cd2d78cb525b3c88de675cb98e2 Mon Sep 17 00:00:00 2001
From: davidfowl <95136+davidfowl@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:22:43 +0000
Subject: [PATCH 3/3] Strip heading tags with a character scanner in the links
test
CodeQL still reported js/incomplete-multi-character-sanitization for the
regex-based tag strip. A scanner that drops everything from < through > has no
partial-match path and produces the same slugs (for example
aspireconfigjson-and-mcp-support for a heading with an inline ).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
.../unit/docs-internal-links.vitest.test.ts | 16 +++++++++++++---
1 file changed, 13 insertions(+), 3 deletions(-)
diff --git a/src/frontend/tests/unit/docs-internal-links.vitest.test.ts b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
index 024484cc3e..8bd99e4618 100644
--- a/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
+++ b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts
@@ -75,6 +75,18 @@ const stripCodeFences = (source: string) => {
.join('\n');
};
+// Headings can contain inline JSX such as MCP; keep only the text.
+const stripTags = (value: string) => {
+ let text = '';
+ let inTag = false;
+ for (const character of value) {
+ if (character === '<') inTag = true;
+ else if (character === '>' && inTag) inTag = false;
+ else if (!inTag) text += character;
+ }
+ return text;
+};
+
const docs = collectDocs(docsDir);
const docsByRoute = new Map(docs.map((file) => [routeOf(file), file]));
const anchorCache = new Map>();
@@ -88,11 +100,9 @@ const anchorsOf = (file: string) => {
for (const [, heading] of source.matchAll(/^#{2,6}\s+(.+?)\s*$/gm)) {
const customId = heading.match(/\{#([^}]+)\}$/)?.[1];
if (customId) anchors.add(customId);
- const text = heading
+ const text = stripTags(heading)
.replace(/\{#[^}]+\}$/, '')
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
- .replace(/<[^>]+>/g, '')
- .replace(/[<>]/g, '')
.replace(/[`*_]/g, '')
.trim();
anchors.add(slugger.slug(text));