Keep docs versions current and default to TypeScript AppHosts

[David Pine (IEvangelist)]

Why this is needed

Current guidance included hard-coded prerelease package versions such as 13.3.0-preview.1.26256.5. Aspire prerelease suffixes move independently from the stable version, so %ASPIRE_VERSION% cannot safely represent them and combining it with an older suffix can produce a package version that never existed. The release audit also searched only the immediately prior version, allowing older stale examples to survive multiple releases.

AppHost language tabs were also authored C# first, which made C# the default for first-time readers even though TypeScript AppHosts are now the intended default documentation experience.

What changed

• add %ASPIRE_VERSION_PREVIEW% as a complete prerelease value and align stable and preview placeholders with the current site AppHost packages
• migrate copy-ready stable and preview examples to contextual placeholders
• broaden release auditing and regression coverage to catch all version-shaped references, including full prerelease build suffixes
• render every aspire-lang tab group TypeScript-first through a central remark transform, avoiding a fragile rewrite of more than 1,000 existing tab groups
• make TypeScript the first/default choice in pivots, integration cards, container API labels, and shared AppHost examples while preserving saved C# choices and query-string overrides
• update contributor and agent guidance so new AppHost examples are authored TypeScript-first with apphost.mts

Validation

• pnpm --dir ./src/frontend exec vitest run --config vitest.config.ts tests/unit/aspire-version-placeholders.vitest.test.ts
• pnpm --dir ./src/frontend exec vitest run --config vitest.config.ts tests/unit/typescript-first-apphost-tabs.vitest.test.ts
• targeted custom-component render coverage for TypeScript-first pivots and apphost.mts
• six targeted desktop Playwright scenarios covering default selection, leftmost order, persistence, query overrides, and integration-gallery links
• focused ESLint and git diff --check

[Copilot]

Pull request overview

Updates aspire.dev documentation and site behavior to keep Aspire version references current (including prerelease placeholders) and to make TypeScript the default first-time AppHost experience across language selectors (tabs, pivots, cards, and related UI).

Changes:

• Introduces %ASPIRE_VERSION_PREVIEW% and expands auditing/tests to prevent stale or impossible prerelease version strings from persisting in current docs.
• Makes TypeScript the first/default option for AppHost language selection via a central remark transform plus UI updates (pivots, integration cards, container API labels, shared code components), while preserving query-string and stored preferences.
• Updates contributor/agent guidance and adds/adjusts unit + e2e coverage for TypeScript-first behavior.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/frontend/tests/unit/typescript-first-apphost-tabs.vitest.test.ts	Adds unit coverage for the remark transform that reorders aspire-lang tabs TypeScript-first.
src/frontend/tests/unit/custom-components.vitest.test.ts	Adds render assertions for TypeScript-first pivots and SimpleAppHostCode ordering.
src/frontend/tests/unit/aspire-version-placeholders.vitest.test.ts	Extends placeholder tests to include %ASPIRE_VERSION_PREVIEW% and scans current docs for version-shaped prerelease suffixes.
src/frontend/tests/e2e/pivot-selector.spec.ts	Updates Playwright coverage to assert TypeScript default and persistence behavior for AppHost tabs.
src/frontend/tests/e2e/integrations-gallery.spec.ts	Updates Playwright coverage to assert TypeScript-first integration gallery links and pivot defaults.
src/frontend/src/content/docs/reference/cli/commands/aspire-ps.mdx	Replaces hard-coded SDK output version with %ASPIRE_VERSION%.
src/frontend/src/content/docs/reference/cli/commands/aspire-new.mdx	Replaces hard-coded template version examples with %ASPIRE_VERSION%.
src/frontend/src/content/docs/reference/cli/commands/aspire-doctor.mdx	Replaces hard-coded prerelease suffix example with %ASPIRE_VERSION_PREVIEW%.
src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx	Replaces hard-coded add-version with %ASPIRE_VERSION%.
src/frontend/src/content/docs/integrations/devtools/browser-logs.mdx	Replaces hard-coded prerelease package version with %ASPIRE_VERSION_PREVIEW%.
src/frontend/src/content/docs/integrations/databases/efcore/migrations.mdx	Replaces fixed package version with %ASPIRE_VERSION%.
src/frontend/src/content/docs/integrations/custom-integrations/hosting-integrations.mdx	Replaces fixed versions with placeholders to keep examples current.
src/frontend/src/content/docs/integrations/cloud/azure/azure-data-explorer.mdx	Replaces hard-coded prerelease package version with %ASPIRE_VERSION_PREVIEW%.
src/frontend/src/content/docs/integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host.mdx	Replaces hard-coded prerelease package version with %ASPIRE_VERSION_PREVIEW%.
src/frontend/src/content/docs/get-started/aspire-sdk-templates.mdx	Replaces fixed template install example with %ASPIRE_VERSION%.
src/frontend/src/content/docs/community/contributor-guide.mdx	Updates contributor guidance and examples to author TypeScript-first AppHost tabs.
src/frontend/src/content/docs/app-host/eventing.mdx	Replaces fixed log “Aspire version” values with %ASPIRE_VERSION%.
src/frontend/src/components/starlight/Head.astro	Changes default aspire-lang preference to TypeScript and keeps preference persistence/query sync.
src/frontend/src/components/SimpleAppHostCode.astro	Switches shared AppHost example tabs to syncKey="aspire-lang" and TypeScript-first ordering.
src/frontend/src/components/PivotSelector.astro	Reorders options to render TypeScript first for key === 'aspire-lang'.
src/frontend/src/components/IntegrationCard.astro	Swaps language buttons so TypeScript docs links render first.
src/frontend/src/components/ContainerImages.astro	Adjusts language pivot defaulting and CSS rules to prefer TypeScript unless explicitly C#.
src/frontend/config/remark-typescript-first-apphost-tabs.mjs	Adds remark plugin to reorder AppHost language tabs TypeScript-first.
src/frontend/config/aspire-versions.mjs	Updates stable version and adds currentAspirePreviewVersion placeholder mapping.
src/frontend/config/aspire-version-placeholders-integration.mjs	Broadens comment to reflect multiple placeholders.
src/frontend/astro.config.mjs	Inserts the new remark plugin before version placeholder replacement.
.github/agents/release-verifier.agent.md	Updates release-verification guidance to scan for all version-shaped references and full prerelease suffixes.
.github/agents/community-toolkit-integration-doc-writer.agent.md	Updates guidance to author TypeScript-first AppHost tabs.
.agents/skills/whatsnew/SKILL.md	Notes currentAspirePreviewVersion as part of version constants.
.agents/skills/whatsnew/references/writing-guidelines.md	Updates parity guidance to TypeScript-first ordering.
.agents/skills/whatsnew/references/whats-new-template.mdx	Adds %ASPIRE_VERSION_PREVIEW% placeholder note and TypeScript-first parity guidance.
.agents/skills/whatsnew/references/05-polish.md	Updates quality gate to require TypeScript-first parity.
.agents/skills/whatsnew/references/03-critique.md	Updates critique checklist to require TypeScript-first parity.
.agents/skills/whatsnew/references/02-research.md	Updates research guidance to TypeScript-first parity.
.agents/skills/whatsnew/references/01-draft-scaffold.md	Updates scaffolding guidance to include stable + preview versions.
.agents/skills/doc-writer/SKILL.md	Updates documentation skill guidance to TypeScript-first AppHost parity patterns.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aspire-repo-bot]

Frontend HTML artifact ready

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

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

[Adam Ratzman (adamint)]

The rendered pages are covered, but the copied Markdown and two new regression tests still have gaps.

[Mitch Denny (mitchdenny)]

Documentation accuracy review

Phase A sources: microsoft/aspire@main 039a7c58f11a01521e49882e26d0d6593b87d9cf; microsoft/aspire@release/13.5 b5f143315ffb6968ea939a9978797a5b20e4c688; published NuGet package indexes. Claims: 22 verified, 0 verified-with-nuance, 0 unverifiable, 0 contradicted. Phase B: 12 affected routes exercised at PR SHA adc77b8787fc2c6c7c7db9e7e21dd2e1cc50bb28; 0 critical issues and 0 warnings.

Phase A — Claim verification

No contradicted or unverifiable claims found.

Verified claims and evidence

1. currentAspireMajorMinorVersion is 13.5 — microsoft/aspire@release/13.5, eng/Versions.props:4-7 defines version prefix 13.5.3.
2. currentAspireVersion is 13.5.3 — same source, and NuGet publishes Aspire.Hosting 13.5.3.
3. currentAspirePreviewVersion is 13.5.3-preview.1.26425.3 — NuGet publishes that exact version; src/apphost/Aspire.Dev.AppHost/Aspire.Dev.AppHost.csproj:14 pins it.
4. Aspire.AppHost.Sdk 13.5.3 exists — verified in the NuGet package index and the site AppHost SDK pin at src/apphost/Aspire.Dev.AppHost/Aspire.Dev.AppHost.csproj:1.
5. Aspire.Hosting 13.5.3 exists — verified in the NuGet package index.
6. Aspire.ProjectTemplates 13.5.3 exists — verified in the NuGet package index.
7. Aspire.Hosting.Kafka 13.5.3 exists — verified in the NuGet package index.
8. Aspire.Microsoft.EntityFrameworkCore.SqlServer 13.5.3 exists — verified in the NuGet package index.
9. Aspire.Hosting.Azure.Kusto 13.5.3-preview.1.26425.3 exists — verified in the NuGet package index.
10. Aspire.Hosting.Browsers 13.5.3-preview.1.26425.3 exists — verified in the NuGet package index.
11. Aspire.Hosting.Foundry 13.5.3-preview.1.26425.3 exists — verified in the NuGet package index.
12. apphost.mts is the current TypeScript AppHost filename — microsoft/aspire@main, src/Aspire.Cli/Projects/DefaultLanguageDiscovery.cs:33-39.
13. aspire-lang tab groups synchronize TypeScript/C# selection page-wide — src/frontend/src/components/starlight/Head.astro:74-153 and the passing pivot-selector e2e coverage.
14. Readers without a saved preference default to TypeScript — src/frontend/src/components/starlight/Head.astro:158-174 and the passing desktop/tablet/mobile e2e checks.
15. An explicit C# selection persists across reloads — src/frontend/src/components/starlight/Head.astro:104-119 and tests/e2e/pivot-selector.spec.ts.
16. The aspire-lang query string takes precedence and synchronizes storage — src/frontend/src/components/starlight/Head.astro:95-119,158-174 and tests/e2e/pivot-selector.spec.ts.
17. PivotSelector renders TypeScript first only for aspire-lang — src/frontend/src/components/PivotSelector.astro:15-35 and tests/unit/custom-components.vitest.test.ts.
18. Integration cards place TypeScript documentation links first — src/frontend/src/components/IntegrationCard.astro:165-186 and tests/e2e/integrations-gallery.spec.ts.
19. Container image API labels default to TypeScript while preserving explicit C# — src/frontend/src/components/ContainerImages.astro:180-224,282-295.
20. SimpleAppHostCode uses canonical synchronized labels and apphost.mts — src/frontend/src/components/SimpleAppHostCode.astro:25-50 and tests/unit/custom-components.vitest.test.ts.
21. Rendered MDX aspire-lang groups are reordered TypeScript-first — src/frontend/config/remark-typescript-first-apphost-tabs.mjs:25-51; all 1,078 groups containing TypeScript were checked after transformation with none left C#-first.
22. Generated Markdown copies receive the same ordering and version replacement — src/frontend/config/aspire-version-placeholders-integration.mjs:31-93 and the focused unit coverage.

Phase B — Doc-tester results

Documentation Test Report

Focus Area: PR #1600 Phase B — version rendering, language tabs, code synchronization, and affected links
Date: 2026-09-02
Tester: doc-tester agent
PR: microsoft/aspire.dev#1600
SHA: adc77b8787fc2c6c7c7db9e7e21dd2e1cc50bb28
Local server: http://localhost:4321/
Browser session: phase-b-pr1600

Routes / Sections Exercised

• /app-host/eventing/ — eventing sections and four AppHost language groups.
• /community/contributor-guide/ — pnpm/npm installation tabs.
• /get-started/aspire-sdk-templates/ — available templates and versioned installation.
• /integrations/cloud/azure/azure-ai-foundry/azure-ai-foundry-host/ — installation and thirteen AppHost language groups.
• /integrations/cloud/azure/azure-data-explorer/ — installation and six AppHost language groups.
• /integrations/custom-integrations/hosting-integrations/ — custom resource guidance, AppHost and shell tabs.
• /integrations/databases/efcore/migrations/ — CLI/Package Manager and deployment-target tabs.
• /integrations/devtools/browser-logs/ — prerequisites and three AppHost language groups.
• /reference/cli/commands/aspire-add/ — name, examples, versions.
• /reference/cli/commands/aspire-doctor/ — name, output examples, versions.
• /reference/cli/commands/aspire-new/ — name, channel/version examples.
• /reference/cli/commands/aspire-ps/ — name, output examples.

Summary

Category	Passed	Failed	Warnings
Content Accuracy	12	0	0
Code Examples	5	0	0
CLI Commands	0	0	0
Links	17	0	0

Critical Issues

None observed.

Warnings

None observed.

Passed Checks

• All 12 routes returned HTTP 200 with expected titles and headings.
• No 404 presentation or browser-console errors occurred.
• No raw %ASPIRE_VERSION% or %ASPIRE_VERSION_MAJOR_MINOR% placeholders remained in visible text or rendered DOM.
• Current values rendered coherently, including 13.5.3, 13.5, and applicable preview versions.
• With clean browser storage, every affected AppHost tab group defaulted to TypeScript.
• Selecting C# synchronized related groups and displayed matching AppHost.cs/C# examples.
• Re-selecting TypeScript restored matching apphost.mts/TypeScript examples.
• Mouse and keyboard tab interaction worked.
• pnpm/npm, .NET CLI/Package Manager Console, and deployment-target tabs displayed their matching content.
• Five affected cross-page links were clicked successfully.
• One section anchor on every route was clicked successfully; all inspected same-page anchor targets existed.

Recommendations

1. Priority fixes: None.
2. Documentation gaps: None identified from the requested visible-behavior scope.
3. Product issues: None observed.

Knowledge Gaps

None. No intrinsic Aspire knowledge was required to assess the requested rendering and interaction behavior.

Test Limitations

These are limitations, not observed failures:

• CLI commands and code samples were not executed or compiled because this Phase B run was explicitly scoped to visible behavior.
• Internal links outside the supplied affected-route list were not browsed.
• Source files, tests, diffs, and upstream repositories were not inspected.

Cleanup

The named browser session was closed, generated browser artifacts were removed, and only the started pnpm dev process was stopped. http://localhost:4321/ was confirmed no longer responsive.

stale