Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions src/frontend/src/content/docs/whats-new/aspire-9-4.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Moving between minor releases of Aspire is simple:
<Sdk Name="Aspire.AppHost.Sdk" Version="9.4.0" />
```

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:
Expand Down Expand Up @@ -82,15 +82,15 @@ 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.
- `aspire add`: Adds a hosting integration package to the apphost.
- `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.
Expand All @@ -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`

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -930,7 +930,7 @@ When a newer version is detected, a friendly notification appears in the Aspire

<Image src={dashboardUpdateNotification} alt="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

Expand Down
12 changes: 5 additions & 7 deletions src/frontend/src/content/docs/whats-new/aspire-9-5.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Moving between minor releases of Aspire is simple:
<Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />
```

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.

Expand Down Expand Up @@ -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:**

Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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/).
</Aside>

### Other tweaks
Expand Down Expand Up @@ -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:**

Expand Down Expand Up @@ -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

Expand Down
172 changes: 172 additions & 0 deletions src/frontend/tests/unit/docs-markdown-link-targets.vitest.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
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 <Steps> 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] &&
marker.length >= fence.length &&
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<string, Set<string>>();

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) {
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 = stripTags(heading)
.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 = /(?<!!)\[[^\]\n]*\]\(([^)\s]+)\)/g;

const findProblems = (file: string) => {
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('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([]);
});
});
Loading