Skip to content

Fix broken links and raw INCLUDE in What's new 9.4/9.5 - #2011

Merged
David Pine (IEvangelist) merged 4 commits into
mainfrom
fix/whats-new-9-4-9-5-broken-links
Nov 1, 2026
Merged

David Pine (IEvangelist) merged 4 commits into
mainfrom
fix/whats-new-9-4-9-5-broken-links

Conversation

@davidfowl

Copy link
Copy Markdown
Contributor

Summary

The "What's new" pages for Aspire 9.4 and 9.5 contain links ported from the old docs site that don't work on aspire.dev, plus one [!INCLUDE] directive that shows up as raw text. The site's links validator misses all of them. It runs with errorOnRelativeLinks: false, treats https://aspire.dev/... as external, and accepts redirect sources.

whats-new/aspire-9-4.mdx

Before After Problem
[Aspire SDK](`microsoft/aspire/sdk`) /get-started/aspire-sdk/ The target is in backticks, so it resolves to a 404
cli-reference/aspire/ /reference/cli/commands/aspire/ Bare relative link → 404
cli-reference/aspire-config/ /reference/cli/commands/aspire-config/ Bare relative link → 404
[!INCLUDE [aspire exec feature flag note](cli/includes/exec-feature-flag-note/)] Inline 🧪 Feature Flag note, in the same style as the aspire deploy note on the same page Rendered as literal text, with a 404 link
cli-reference/aspire-deploy/ /reference/cli/commands/aspire-deploy/ Bare relative link → 404
fundamentals/orchestrate-resources.md#express-external-service-resources /reference/api/csharp/aspire.hosting/externalservicebuilderextensions/ 404. No conceptual page covers AddExternalService, so it links to the API reference
https://aspire.dev/app-host/eventing/#apphost-life-cycle-events #apphost-eventing Anchor doesn't exist
https://aspire.dev/app-host/configuration/#aspire-version-update-notifications #version-update-notifications Anchor doesn't exist

whats-new/aspire-9-5.mdx

Before After Problem
[Aspire SDK](`microsoft/aspire/sdk`) /get-started/aspire-sdk/ The target is in backticks → 404
cli-reference/aspire-config-set/ /reference/cli/commands/aspire-config-set/ Bare relative link → 404
"For more information, see aspire exec command reference." Sentence removed 404. aspire exec is no longer in the CLI, and /reference/cli/commands/aspire-exec/ redirects to aspire-resource, which is a different command (#1814)
cli-reference/aspire-config/ /reference/cli/commands/aspire-config/ Bare relative link → 404
/integrations/reverse-proxies/yarp/#multi-stage-docker-builds #static-file-serving Anchor doesn't exist. The static-files section is the one the text describes
/integrations/messaging/rabbitmq/rabbitmq-client/#auto-activation /integrations/messaging/rabbitmq/rabbitmq-connect/#auto-activation The old path is a meta-refresh redirect stub that drops #auto-activation

Regression test: the new tests/unit/docs-markdown-link-targets.vitest.test.ts scans English docs markdown (skipping code fences) for these patterns:

  • [!INCLUDE directives
  • link targets wrapped in backticks
  • bare relative targets
  • anchored links to redirect sources
  • https://aspire.dev/... links to missing pages or missing heading anchors

It skips the same paths the links validator excludes (/reference/api/, /hub/, /i18n/).

Scope: open PR #1995 covers a different set of link gaps (dashboard anchors and Azure pages) and doesn't touch these lines. Other open PRs that edit these files (#1933, #1896, #1876) don't change these links either.

Third-party links and affiliations

None.

Validation

  • Regression test: fails on main with 15 problems across the two files, and passes with this change (2/2).
  • Unit tests: bun run test:unit → 85 files, 1122 passed, 1 skipped.
  • Lint: bun run lint passes.
  • Playwright, against the local dev server: opened both pages and requested every changed link, checking the target anchor exists.
    • Before: 12 failures (404s, missing anchors, plus the raw [!INCLUDE text on 9.4).
    • After: all 12 links resolve, every anchor is present, and there is no [!INCLUDE text.
  • Redirect behaviour: checked against the production build artifact from main CI. rabbitmq-client/#auto-activation lands on rabbitmq-connect/ with an empty hash, so the anchor is lost.

Before: the 9.4 aspire exec section renders the raw directive.

Before: Aspire 9.4 What's new shows literal "[!INCLUDE aspire exec feature flag note]" text

After: the feature-flag note renders.

After: Aspire 9.4 What's new shows the Feature Flag note for aspire exec

🤖 Posted by AspireAgent (AI Agent)

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>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2011. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2011 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@davidfowl
David Fowler (davidfowl) marked this pull request as ready for review October 31, 2026 16:09
Copilot AI balanced review requested due to automatic review settings October 31, 2026 16:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The closing-fence check accepts delimiters shorter than the opening fence, prematurely ending a nested code sample and causing real “See also” links to be skipped.

1 open issue
What changed in this PR

This PR repairs migrated links and an unsupported include directive in the Aspire 9.4 and 9.5 release notes, and adds regression checks for Markdown patterns missed by the site’s links validator.

Changes:

  • Corrects link paths and heading anchors, and removes an obsolete command-reference link.
  • Replaces the raw [!INCLUDE] directive with an inline feature-flag note.
  • Adds English-docs checks for malformed targets, anchored redirects, and broken absolute aspire.dev links.
File Description
src/​frontend/​tests/​unit/​docs-markdown-link-targets.vitest.test.ts Adds Markdown link-target regression checks.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-9-5.mdx Repairs links and removes the obsolete aspire exec reference link.
src/​frontend/​src/​content/​docs/​whats-new/​aspire-9-4.mdx Repairs links and replaces the unsupported include directive.

Review effort: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) enabled auto-merge (squash) November 1, 2026 14:48
@IEvangelist
David Pine (IEvangelist) merged commit e4e5049 into main Nov 1, 2026
19 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the fix/whats-new-9-4-9-5-broken-links branch November 1, 2026 14:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants