Repository navigation
Fix broken Dashboard landing anchors and relative docs links - #1995
Conversation
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>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
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>
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 <abbr>). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the documentation link fixes and added regression coverage.
No open issues 🎉
What changed in this PR
Fixes seven broken internal links in the English documentation used by locale fallback pages and adds regression coverage for link types the existing validator skips.
Changes:
- Corrects five Dashboard landing-page links to existing section anchors.
- Replaces two broken relative Markdown links with site-relative URLs and corrects the Redis Insight anchor.
- Adds unit validation for expression-prop links and relative Markdown links, checking destination pages and heading IDs.
| File | Description |
|---|---|
src/frontend/tests/unit/docs-internal-links.vitest.test.ts |
Adds internal-link regression coverage for English docs. |
src/frontend/src/content/docs/reference/cli/commands/aspire-dashboard-run.mdx |
Fixes the Dashboard configuration URL. |
src/frontend/src/content/docs/integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host.mdx |
Fixes the Redis hosting URL and Redis Insight anchor. |
src/frontend/src/content/docs/dashboard/index.mdx |
Corrects tracing, structured logs, and metrics anchors. |
Review effort: Balanced
Project documentation reviewReviewed PR #1995, base Phase A - Claim verificationSeven changed cross-reference claims: 7 verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted. No actionable accuracy findings. The changed links point to the intended owning documentation and headings. No new package, version, API sample, or CLI invocation was introduced. Source refs: Verified claims and source evidence
Owning product evidence:
The site's configured default locale is English ( Phase B - Independent doc-tester resultsComplete: 14 successful link clicks across the three changed English pages and their Danish fallback equivalents; 0 critical issues and 0 link-navigation warnings. Two preview-environment caveats are recorded below. This browser phase was blind to product source and the regression test implementation. Full independent doc-tester report (verbatim)Documentation Test ReportFocus Area: Phase B only — independent blind browser validation of the seven changed documentation links in microsoft/aspire.dev PR #1995, plus actual untranslated-locale fallback for its three changed pages. Summary
Pass counts concern navigation, rendered destination headings, and meaningful labels—not verification of underlying Aspire features. Critical IssuesNone found in the seven changed links or three tested fallback routes. WarningsWarning 1: Lightweight preview lacks the live-status backendLocation: Local preview Warning 2: Preview footer SHA is not the detached PR headLocation: Site footer. Passed ChecksSeven English link clicksAll destinations below are exact browser URLs. Every fragment matched an existing rendered, visible heading with the indicated ID. The configuration link has no fragment, so its rendered page-title heading was checked instead.
The three cards' full accessible labels include their feature title and explanatory text, rather than only the repeated words “Learn more”:
The Redis tip visibly introduces customization of the underlying Redis resource and names Redis Insight, Redis Commander, a data volume, and a data bind mount before “For more information, see Redis Hosting integration.” The link lands at the Redis Insight section of the Redis hosting guide. The destination label and topic are meaningful; this run does not claim to verify those customization APIs. All seven changed hrefs are site-relative and have a slash before any fragment. Actual locale fallback, discovered through visible UII opened the visible “Select language” combobox on the rendered site, observed its options, and selected Dansk. I did not inspect translation files, locale configuration, or tests to choose a supposedly untranslated locale. All three pages visibly showed the Danish fallback notice:
Their content remained English, with
I additionally clicked all seven changed links from those actual fallback pages. They reached exactly the same seven English destination URLs and heading IDs recorded above. The observed behavior is that these fallback-page links leave Setup, commands, results, and browser methodologyBoth required skills were invoked, and their actual local
Commands were run from the worktree root unless noted:
Early browser experiments encountered a 5-second click timeout, aborted navigation, and “Execution context was destroyed” while client-side transitions were still pending. One configuration-heading wait incorrectly expected “Dashboard configuration” rather than the actual “Aspire dashboard configuration reference”; this was corrected to observe the real rendered heading. A broad Cleanup and persistent state
Recommendations
Knowledge Gaps and Honest Limits
This is a top-level conversation report, not a formal approval or change-request verdict. No fixes, edits to the PR, pushes, or merges were made. |
Project code reviewReviewed PR #1995 against No actionable, high-confidence code findings. The new internal-link regression checker is correct and adequately covered for its stated scope: English docs' literal expression-prop Test coverage
The checker deliberately supplements, rather than replaces, Starlight's build-time validator. This review does not claim exhaustive validation of arbitrary MDX expressions, generated API/Dev Hub destinations, external URLs, or bare relative links without This is a top-level conversation report, not a formal approval or change-request verdict. No fixes, edits to the PR, pushes, or merges were made. |
## 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](cli-reference/aspire-exec/) 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](https://github.com/user-attachments/assets/6162ca7e-9bd6-4df9-8271-af24daae09e1) **After:** the feature-flag note renders.  **🤖 Posted by AspireAgent (AI Agent)** --------- Co-authored-by: davidfowl <95136+davidfowl@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Summary
Fixes seven broken internal links in the English docs. Every locale falls back to these pages, so each broken link appears on all 15 locales. The links validator didn't flag them because it never inspects these two kinds of link:
starlight-links-validatorruns witherrorOnRelativeLinks: false, so it skips./and../links entirely.hrefattributes. It can't see hrefs passed through JSX expression props such ascta={{ href: '…' }}orcapabilities={[{ href: '…' }]}./dashboard/(2ImageShowcaseCTAs + 3CapabilityGridcards)/dashboard/explore/#traces,#structured-logs,#metrics. These ids don't exist, so the link lands at the top of a long page#traces-page,#structured-logs-page,#metrics-page, the same anchors thatdashboard/standalone.mdxanddata/dev-hub.tsalready use/reference/cli/commands/aspire-dashboard-run/../../../dashboard/configuration/→/reference/dashboard/configuration/(404)/dashboard/configuration//integrations/cloud/azure/azure-cache-redis/azure-cache-redis-host/../../../caching/redis/redis-host/#…-redis-insights→/integrations/cloud/caching/redis/redis-host/(404), and the anchor was misspelled/integrations/caching/redis/redis-host/#add-redis-resource-with-redis-insightThe fixed links are absolute, so
starlight-links-validatornow checks the two Markdown ones at build time. A new unit test,tests/unit/docs-internal-links.vitest.test.ts, covers the gap for the English docs. It resolves expression-prophref:values and.//../Markdown links to an existing docs page and, when there's a fragment, to an existing heading id. It follows the existing pattern indev-glossary.vitest.test.tsand slugs headings withgithub-slugger, as Starlight does. Like the validator config, it skips/reference/api/and/hub/.How this was found
I crawled main's CI
frontend-distartifact, the production build of29550055from run 41062457941, covering all 8,327 non-API HTML pages. I checked every internal<a href>against the built files and ids. Before this change the live site behaves as follows:https://aspire.dev/reference/dashboard/configuration/returns 404.https://aspire.dev/integrations/cloud/caching/redis/redis-host/returns 404.https://aspire.dev/dashboard/explore/only hasid="traces-page",id="structured-logs-page"andid="metrics-page".The crawl also found broken links that this PR leaves alone:
.mdpage-action links: covered by Fix Markdown page actions on untranslated locale pages #1990.whats-new/aspire-9-4.mdxandaspire-9-5.mdx: these files are being edited by open PRs Add Aspire azd transition page and deployment notices #1933, Resolve release sync conflicts for release/17.0 #1896 and [docs] Document Traces page Spans column overflow tooltip #1876.data/samples.json): it comes from the upstream samples repo.Third-party links and affiliations
None.
Validation
npx vitest run: 84 files passed; 1,121 tests passed and 1 skipped.npx eslint . --max-warnings 0passes, and the new test file is Prettier-formatted.astro dev, after the fix:/dashboard/renders the five#*-pagehrefs, and each target id exists on/dashboard/explore/.🤖 Posted by AspireAgent (AI Agent)