From 4a732c156cac2fe15c75a9c5883838bf4e064cb7 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sat, 31 Oct 2026 15:19:19 +0000 Subject: [PATCH 1/4] Fix broken links and raw INCLUDE in What's new 9.4/9.5 Replace bare relative cli-reference links, backtick link targets, stale anchors, and a leftover [!INCLUDE] directive with current targets, and add a unit test that scans docs markdown for these link patterns that the links validator does not catch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/whats-new/aspire-9-4.mdx | 16 +- .../src/content/docs/whats-new/aspire-9-5.mdx | 12 +- .../docs-markdown-link-targets.vitest.test.ts | 151 ++++++++++++++++++ 3 files changed, 164 insertions(+), 15 deletions(-) create mode 100644 src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts diff --git a/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx b/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx index 80cad2226c..8237942b23 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9-4.mdx @@ -44,7 +44,7 @@ Moving between minor releases of Aspire is simple: ``` - For more information, see [Aspire SDK](`microsoft/aspire/sdk`). + For more information, see [Aspire SDK](/get-started/aspire-sdk/). 1. Check for any NuGet package updates, either using the NuGet Package Manager in Visual Studio or the **Update NuGet Package** command from C# Dev Kit in VS Code. 1. Update to the latest Aspire templates by running the following .NET command line: @@ -82,7 +82,7 @@ You must upgrade your project to Aspire 9.4+ in order to use the latest CLI feat ### ๐ŸŽฏ CLI Commands -The Aspire CLI has the following [commands](cli-reference/aspire/): +The Aspire CLI has the following [commands](/reference/cli/commands/aspire/): - `aspire new`: Creates a new Aspire project from templates. - `aspire run`: Finds and runs the existing apphost from anywhere in the repo. @@ -90,7 +90,7 @@ The Aspire CLI has the following [commands](cli-reference/aspire/): - `aspire config [get|set|delete|list]`: Configures Aspire settings and feature flags. - `aspire publish` (Preview): Generates deployment artifacts based on the apphost. -In addition to these core commands, we have two beta commands behind [feature flags](cli-reference/aspire-config/): +In addition to these core commands, we have two beta commands behind [feature flags](/reference/cli/commands/aspire-config/): - `aspire exec`: Invokes an arbitrary command in the context of an executable resource defined in the apphost (ie, inheriting its environment variables). - `aspire deploy`: Extends the capabilities of `aspire publish` to actively deploy to a target environment. @@ -116,7 +116,7 @@ aspire exec --start-resource my-worker -- npm run build - **Resource targeting** with `--resource` or `--start-resource` options - **Command execution** in the context of your Aspirified application -[!INCLUDE [aspire exec feature flag note](cli/includes/exec-feature-flag-note/)] +๐Ÿงช **Feature Flag**: The `aspire exec` command is behind a feature flag and **disabled by default** in this release. It must be explicitly enabled with `aspire config set features.execCommandEnabled true`. #### `aspire deploy` @@ -237,7 +237,7 @@ The enhanced output is particularly valuable for: - **Container-based deployments** where build and push operations need clear status reporting - **Team environments** where deployment logs need to be easily interpreted by different team members -For more information about publishing and deploying Aspire apps, see [aspire deploy](cli-reference/aspire-deploy/). +For more information about publishing and deploying Aspire apps, see [aspire deploy](/reference/cli/commands/aspire-deploy/). ## ๐Ÿ–ฅ๏ธ App model enhancements @@ -457,7 +457,7 @@ For more information, including supported input types, see the [Interaction Serv ### ๐ŸŒ External service modeling -Modern applications frequently need to integrate with external APIs, third-party services, or existing infrastructure that isn't managed by Aspire. Aspire 9.4 introduces first-class support for [modeling external services](fundamentals/orchestrate-resources.md#express-external-service-resources) as resources in your application graph. +Modern applications frequently need to integrate with external APIs, third-party services, or existing infrastructure that isn't managed by Aspire. Aspire 9.4 introduces first-class support for [modeling external services](/reference/api/csharp/aspire.hosting/externalservicebuilderextensions/) as resources in your application graph. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -653,7 +653,7 @@ public async Task Should_ResetCache_WhenTestStarts() ### ๐Ÿ”„ Resource lifecycle events -Aspire 9.4 introduces convenient extension methods on `Aspire.Hosting.ApplicationModel.IResourceBuilder`1` that make it much easier to subscribe to [lifecycle events](https://aspire.dev/app-host/eventing/#apphost-life-cycle-events) directly on resources, providing a cleaner and more intuitive API. +Aspire 9.4 introduces convenient extension methods on `Aspire.Hosting.ApplicationModel.IResourceBuilder`1` that make it much easier to subscribe to [lifecycle events](https://aspire.dev/app-host/eventing/#apphost-eventing) directly on resources, providing a cleaner and more intuitive API. ```csharp var builder = DistributedApplication.CreateBuilder(args); @@ -930,7 +930,7 @@ When a newer version is detected, a friendly notification appears in the Aspire Screenshot of dashboard showing an update notification. -Aspire only shows notifications when a newer version is available, and the checks happen in the background without impacting application startup or performance. The upgrade check system can be disabled by setting the `ASPIRE_VERSION_CHECK_DISABLED` environment variable to `true`. For more information, see [Aspire version update notifications](https://aspire.dev/app-host/configuration/#aspire-version-update-notifications). +Aspire only shows notifications when a newer version is available, and the checks happen in the background without impacting application startup or performance. The upgrade check system can be disabled by setting the `ASPIRE_VERSION_CHECK_DISABLED` environment variable to `true`. For more information, see [Aspire version update notifications](https://aspire.dev/app-host/configuration/#version-update-notifications). ### ๐Ÿ“‹ Parameters and connection strings visible in dashboard diff --git a/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx b/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx index 49d13365ee..ce62b81d3a 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-9-5.mdx @@ -57,7 +57,7 @@ Moving between minor releases of Aspire is simple: ``` - For more information, see [Aspire SDK](`microsoft/aspire/sdk`). + For more information, see [Aspire SDK](/get-started/aspire-sdk/). 1. Check for any NuGet package updates, either using the NuGet Package Manager in Visual Studio or the **Update NuGet Package** command from C# Dev Kit in Visual Studio (VS) Code. @@ -117,7 +117,7 @@ aspire config set features.singlefileAppHostEnabled true aspire config set features.minimumSdkCheckEnabled false ``` -For more information, see [aspire config set command](cli-reference/aspire-config-set/). +For more information, see [aspire config set command](/reference/cli/commands/aspire-config-set/). **SDK version requirements:** @@ -150,8 +150,6 @@ Aspire 9.5 builds on the 9.4 preview and adds several key improvements: - Fail-fast argument validation with clearer error messages. - Improved help and usage text for better developer experience. -For more information, see [aspire exec command](cli-reference/aspire-exec/) reference. - #### Basic usage examples ```bash title='Aspire CLI' @@ -179,7 +177,7 @@ This command is disabled by default. To use it, turn on the feature toggle by ru aspire config set features.execCommandEnabled true ``` -For more information, see [aspire config command](cli-reference/aspire-config/). +For more information, see [aspire config command](/reference/cli/commands/aspire-config/). ### Other tweaks @@ -410,7 +408,7 @@ var frontend = builder.AddYarp("frontend") builder.Build().Run(); ``` -For more information, see [Multi-stage Docker builds](https://aspire.dev/integrations/reverse-proxies/yarp/#multi-stage-docker-builds). +For more information, see [Multi-stage Docker builds](https://aspire.dev/integrations/reverse-proxies/yarp/#static-file-serving). **Hybrid static + API gateway:** @@ -480,7 +478,7 @@ var builder = WebApplication.CreateBuilder(args); builder.AddRabbitMQClient("messaging", o => o.DisableAutoActivation = false); ``` -For more information, see [RabbitMQ integration - Auto activation](/integrations/messaging/rabbitmq/rabbitmq-client/#auto-activation). +For more information, see [RabbitMQ integration - Auto activation](/integrations/messaging/rabbitmq/rabbitmq-connect/#auto-activation). ### Redis integration improvements diff --git a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts new file mode 100644 index 0000000000..c6e965be9b --- /dev/null +++ b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts @@ -0,0 +1,151 @@ +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'; +import { redirects } from '../../config/redirects.mjs'; + +// starlight-links-validator treats `https://aspire.dev/...` links as external, skips +// bare relative links (`errorOnRelativeLinks: false`) and accepts redirect sources +// without checking their anchors. This test covers those Markdown link forms, plus +// targets that aren't URLs at all, for the English docs every locale falls back to. + +const docsDir = fileURLToPath(new URL('../../src/content/docs/', import.meta.url)); +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 tests or generated pages. +const skippedPrefixes = ['/reference/api/', '/hub/', '/i18n/']; +const redirectSources = new Set(Object.keys(redirects)); + +const collectDocs = (directory: string): string[] => + readdirSync(directory).flatMap((entry) => { + const fullPath = path.join(directory, entry); + if (statSync(fullPath).isDirectory()) { + return path.resolve(directory) === path.resolve(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 proseLines = (source: string) => { + let fence: string | undefined; + return source.split('\n').map((line) => { + const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1]; + if (fence) { + if (marker && marker[0] === fence[0] && line.trim() === marker) fence = undefined; + return ''; + } + if (marker) { + fence = marker; + return ''; + } + return line; + }); +}; + +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 = proseLines(readFileSync(file, 'utf8')).join('\n'); + anchors = new Set(); + for (const [, heading] of source.matchAll(/^#{2,6}\s+(.+?)\s*$/gm)) { + const text = heading + .replace(/<[^>]*>/g, '') + .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 markdownLinkTarget = /(? { + const source = path.relative(docsDir, file).split(path.sep).join('/'); + const problems: string[] = []; + proseLines(readFileSync(file, 'utf8')).forEach((line, index) => { + const at = `${source}:${index + 1}`; + if (line.includes('[!INCLUDE')) problems.push(`${at}: unsupported [!INCLUDE] directive`); + for (const [, target] of line.matchAll(/\]\((`[^`)]*`)\)/g)) { + problems.push(`${at}: ${target} is inline code, not a link target`); + } + const withoutCode = line.replace(/`[^`]*`/g, ''); + for (const [, target] of withoutCode.matchAll(markdownLinkTarget)) { + if (!/^(?:[a-z][a-z0-9+.-]*:|\/|\.|#)/i.test(target)) { + problems.push(`${at}: ${target} is relative to the page URL; use a root-relative link`); + continue; + } + const url = target.startsWith('/') + ? new URL(target, 'https://aspire.dev') + : /^https:\/\/aspire\.dev\//.test(target) + ? new URL(target) + : undefined; + if (!url) continue; + const pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`; + if ( + skippedPrefixes.some((prefix) => pathname.startsWith(prefix)) || + /\.[a-z0-9]+\/$/i.test(pathname) + ) + continue; + const anchor = decodeURIComponent(url.hash.slice(1)); + // Redirect pages use a meta refresh to the bare destination, which drops the anchor. + if (redirectSources.has(pathname)) { + if (anchor) problems.push(`${at}: ${target} loses its anchor through a redirect`); + continue; + } + if (!target.startsWith('https://aspire.dev/')) continue; + const destination = docsByRoute.get(pathname); + if (!destination) problems.push(`${at}: ${target} resolves to a missing page`); + else if (anchor && !anchorsOf(destination).has(anchor)) { + problems.push(`${at}: ${target} points to a missing heading #${anchor}`); + } + } + }); + return problems; +}; + +describe('English docs Markdown link targets', () => { + it('finds the English docs', () => { + expect(docsByRoute.get('/whats-new/aspire-9-4/')).toBeDefined(); + expect(docs.length).toBeGreaterThan(100); + }); + + it('uses resolvable link targets that starlight-links-validator does not check', () => { + expect(docs.flatMap(findProblems)).toEqual([]); + }); +}); From fd1e44408dcaa92d6227e8d6dfbd6963cea6b3b9 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sat, 31 Oct 2026 15:39:00 +0000 Subject: [PATCH 2/4] Strip leftover angle brackets in heading anchor text (CodeQL) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../tests/unit/docs-markdown-link-targets.vitest.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts index c6e965be9b..372681b9d5 100644 --- a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts +++ b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts @@ -82,6 +82,7 @@ const anchorsOf = (file: string) => { for (const [, heading] of source.matchAll(/^#{2,6}\s+(.+?)\s*$/gm)) { const text = heading .replace(/<[^>]*>/g, '') + .replace(/[<>]/g, '') .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') .replace(/[`*_]/g, '') .trim(); From b085c214020af9b9d8978fb7d1a0c759ccabacb1 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sat, 31 Oct 2026 15:41:30 +0000 Subject: [PATCH 3/4] Strip heading tags until stable (CodeQL) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../unit/docs-markdown-link-targets.vitest.test.ts | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts index 372681b9d5..f8594ee253 100644 --- a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts +++ b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts @@ -73,6 +73,15 @@ const docs = collectDocs(docsDir); const docsByRoute = new Map(docs.map((file) => [routeOf(file), file])); const anchorCache = new Map>(); +const stripTags = (value: string) => { + let previous; + do { + previous = value; + value = value.replace(/<[^>]*>/g, ''); + } while (value !== previous); + return value; +}; + const anchorsOf = (file: string) => { let anchors = anchorCache.get(file); if (!anchors) { @@ -80,9 +89,7 @@ const anchorsOf = (file: string) => { const source = proseLines(readFileSync(file, 'utf8')).join('\n'); anchors = new Set(); for (const [, heading] of source.matchAll(/^#{2,6}\s+(.+?)\s*$/gm)) { - const text = heading - .replace(/<[^>]*>/g, '') - .replace(/[<>]/g, '') + const text = stripTags(heading) .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') .replace(/[`*_]/g, '') .trim(); From eab516a032d46580e2810ee90f85dfe6ad4b99d7 Mon Sep 17 00:00:00 2001 From: davidfowl <95136+davidfowl@users.noreply.github.com> Date: Sat, 31 Oct 2026 20:18:36 +0000 Subject: [PATCH 4/4] Require closing code fence to be at least as long as the opening fence Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../docs-markdown-link-targets.vitest.test.ts | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts index f8594ee253..5ec40330ea 100644 --- a/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts +++ b/src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts @@ -58,7 +58,13 @@ const proseLines = (source: string) => { return source.split('\n').map((line) => { const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1]; if (fence) { - if (marker && marker[0] === fence[0] && line.trim() === marker) fence = undefined; + if ( + marker && + marker[0] === fence[0] && + marker.length >= fence.length && + line.trim() === marker + ) + fence = undefined; return ''; } if (marker) { @@ -153,6 +159,13 @@ describe('English docs Markdown link targets', () => { expect(docs.length).toBeGreaterThan(100); }); + it('keeps shorter delimiters inside a longer code fence', () => { + const source = ['````md', '```', '[inside](code)', '```', '````', '[after](/after/)'].join( + '\n' + ); + expect(proseLines(source)).toEqual(['', '', '', '', '', '[after](/after/)']); + }); + it('uses resolvable link targets that starlight-links-validator does not check', () => { expect(docs.flatMap(findProblems)).toEqual([]); });