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..8bd99e4618 --- /dev/null +++ b/src/frontend/tests/unit/docs-internal-links.vitest.test.ts @@ -0,0 +1,153 @@ +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'); +}; + +// 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>(); + +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 = stripTags(heading) + .replace(/\{#[^}]+\}$/, '') + .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') + .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([]); + }); +});