Refactor AppHost docs and add a localized site tour by IEvangelist · Pull Request #666 · microsoft/aspire.dev

IEvangelist · 2026-04-02T21:14:52Z

Summary

consolidate the split AppHost documentation into shared guides with synced C# and TypeScript tabs, including the first-app, deploy-first-app, and add-existing-app flows
add a full site tour experience with target highlighting, focus management, quick navigation, restart/resume behavior, overlay dismissal, and localized strings across all supported locales
refresh the Starlight shell and related UI pieces, including the header, sidebar, footer preferences/socials, install CLI modal, edit link, page title, integration grid, and shared site styles
move analytics assets into public scripts and update the tracking wiring
update supporting docs, sidebar/topic configuration, breadcrumb routing, API reference pages, sample/stats scripts, and related guidance to align with the new AppHost and navigation work

More detail

Added AppHostLangPivot.astro and reworked documentation to reduce C#/TypeScript duplication while keeping AppHost-specific implementation details in tabs.
Removed several split getting-started pages and merged them into unified scenario-based guides.
Added SiteTour.astro, tour trigger/help affordances, footer preferences targeting, localized copy in en.json plus the non-English locale files, and the supporting header/sidebar/head integration changes.
Moved 1ds.js and track.js from page-level sources into public/scripts/analytics/ and updated the site to use the new script locations.
Included follow-on fixes for breadcrumbs and route normalization, sample repo references, contributor-guide markdown cleanup, sidebar topic data, redirects, API reference routing, and related documentation updates.

Testing

Validated changed files with editor diagnostics where applicable
Did not run a full build or test pass

- Introduced `AppHostLangPivot` component to streamline language-specific code presentation in documentation. - Updated `resource-mcp-servers.mdx` to utilize the new `AppHostLangPivot` for C# and TypeScript code examples. - Modified `what-is-aspire.mdx` to implement `AppHostLangPivot` for improved clarity in multi-language AppHost examples. - Adjusted Japanese documentation to reflect changes in links and content structure. - Enhanced CSS for sidebar responsiveness and improved layout for API reference pages. - Fixed links in various documentation files to point to the correct paths for creating Aspire applications.

…nd UI components - Added SiteTour component to manage and display a guided tour for users. - Integrated tour steps for key UI elements including app host selector, sidebar toggle, and page actions. - Enhanced PageTitle and Sidebar components with data attributes for tour targeting. - Introduced new SVG icon for help in site navigation. - Updated prerequisites documentation to include margin for better layout.

…pository

- Introduced 1ds.js to initialize Application Insights for analytics tracking. - Added track.js to bind click event tracking for elements with data attributes. - Implemented checks to prevent multiple initializations and bindings. - Enhanced debugging output for better traceability during analytics operations.

…t and usability

…crumbs

- Implemented site tour translations in Indonesian, Italian, Japanese, Korean, Brazilian Portuguese, European Portuguese, Russian, Turkish, Ukrainian, and Simplified Chinese. - Each language includes labels, tooltips, hints, and steps for the site tour feature.

Copilot

Pull request overview

This PR refactors Aspire AppHost documentation to reduce C#/TypeScript duplication (via shared pages and language selectors), introduces a localized in-product site tour across the Starlight shell, and updates supporting navigation, breadcrumbs, analytics script delivery, and sample/stats wiring to match the new structure.

Changes:

Consolidates getting-started AppHost flows into unified guides with synced language selection patterns.
Adds a full site tour system (targets, focus management, resume/restart state, localized strings) and updates header/footer/sidebar UI to support it.
Moves analytics initialization/tracking scripts to static public assets and updates head wiring, plus aligns sidebars/redirects/breadcrumb routing to new slugs.

Reviewed changes

Copilot reviewed 108 out of 110 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tmp/aspire-lang-margin-patches/patch-1.txt	Adds patch artifact file (appears to be local-only).
tmp/aspire-lang-margin-patches/patch-2.txt	Adds patch artifact file (appears to be local-only).
tmp/aspire-lang-margin-patches/patch-3.txt	Adds patch artifact file (appears to be local-only).
tmp/aspire-lang-margin-patches/patch-4.txt	Adds patch artifact file (appears to be local-only).
tmp/aspire-lang-margin-patches/patch-5.txt	Adds patch artifact file (appears to be local-only).
src/frontend/src/utils/content-breadcrumbs.ts	Makes breadcrumb resolution more robust (supports id/entry fields; strips md/mdx extensions).
src/frontend/src/styles/site.css	Adjusts sidebar sizing/collapse behavior and TOC layout when topic-nav is active.
src/frontend/src/pages/track.js	Removes dynamic tracking endpoint (replaced by static public script).
src/frontend/src/pages/1ds.js	Removes dynamic 1DS endpoint (replaced by static public script).
src/frontend/src/pages/reference/api/typescript/index.astro	Adds breadcrumb UI and updates “first app” link to new unified route.
src/frontend/src/pages/reference/api/typescript/[module]/index.astro	Removes `pageActions` override in frontmatter.
src/frontend/src/pages/reference/api/typescript/[module]/[item]/index.astro	Removes `pageActions` override in frontmatter.
src/frontend/src/pages/reference/api/typescript/[module]/[item]/[member]/index.astro	Removes `pageActions` override in frontmatter.
src/frontend/src/pages/reference/api/csharp/index.astro	Adds breadcrumb UI.
src/frontend/src/pages/reference/api/csharp/[package]/index.astro	Removes `pageActions` override in frontmatter.
src/frontend/src/pages/reference/api/csharp/[package]/[type]/index.astro	Removes `pageActions` override in frontmatter.
src/frontend/src/pages/reference/api/csharp/[package]/[type]/[memberKind].astro	Removes `pageActions` override in frontmatter.
src/frontend/public/scripts/analytics/track.js	Adds static click tracking script.
src/frontend/public/scripts/analytics/1ds.js	Adds static OneDS initialization script.
src/frontend/src/content/i18n/en.json	Adds site tour localized strings (English).
src/frontend/src/content/i18n/da.json	Adds site tour localized strings (Danish).
src/frontend/src/content/i18n/de.json	Adds site tour localized strings (German).
src/frontend/src/content/i18n/es.json	Adds site tour localized strings (Spanish).
src/frontend/src/content/i18n/fr.json	Adds site tour localized strings (French).
src/frontend/src/content/i18n/hi.json	Adds site tour localized strings (Hindi).
src/frontend/src/content/i18n/id.json	Adds site tour localized strings (Indonesian).
src/frontend/src/content/i18n/it.json	Adds site tour localized strings (Italian).
src/frontend/src/content/i18n/ja.json	Adds site tour localized strings (Japanese).
src/frontend/src/content/i18n/ko.json	Adds site tour localized strings (Korean).
src/frontend/src/content/i18n/pt-BR.json	Adds site tour localized strings (Portuguese - Brazil).
src/frontend/src/content/i18n/pt-PT.json	Adds site tour localized strings (Portuguese - Portugal).
src/frontend/src/content/i18n/ru.json	Adds site tour localized strings (Russian).
src/frontend/src/content/i18n/tr.json	Adds site tour localized strings (Turkish).
src/frontend/src/content/i18n/uk.json	Adds site tour localized strings (Ukrainian).
src/frontend/src/content/i18n/zh-CN.json	Adds site tour localized strings (Simplified Chinese).
src/frontend/src/content/docs/whats-new/aspire-9-3.mdx	Updates samples repo link to microsoft org.
src/frontend/src/content/docs/whats-new/aspire-13.mdx	Updates unified quickstart/tutorial links to new consolidated slugs.
src/frontend/src/content/docs/whats-new/aspire-13-2.mdx	Updates GitHub org links and reference links to new org.
src/frontend/src/content/docs/testing/write-your-first-test.mdx	Updates “first app” link to new consolidated slug.
src/frontend/src/content/docs/ja/whats-new/aspire-13.mdx	Updates Japanese “first app/deploy” links to consolidated slugs.
src/frontend/src/content/docs/ja/testing/write-your-first-test.mdx	Updates Japanese “first app” link to consolidated slug.
src/frontend/src/content/docs/get-started/what-is-aspire.mdx	Replaces synced tabs with an Aspire language PivotSelector + Pivot blocks.
src/frontend/src/content/docs/ja/get-started/what-is-aspire.mdx	Same as above for Japanese page.
src/frontend/src/content/docs/get-started/resource-mcp-servers.mdx	Switches AppHost code examples to `Tabs syncKey='aspire-lang'` and updates formatting.
src/frontend/src/content/docs/get-started/prerequisites.mdx	Converts language choice to synced tabs and updates callout syntax; updates Codespaces org.
src/frontend/src/content/docs/ja/get-started/prerequisites.mdx	Updates Codespaces org.
src/frontend/src/content/docs/get-started/github-codespaces.mdx	Updates Dev Container template org and template_owner query param.
src/frontend/src/content/docs/get-started/dev-containers.mdx	Updates Dev Container template org and template_owner query param.
src/frontend/src/content/docs/get-started/aspire-sdk-templates.mdx	Updates consolidated “first app” link and samples repo org.
src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx	Updates code example tabs to `syncKey='aspire-lang'` and formatting.
src/frontend/src/content/docs/get-started/app-host.mdx	Updates “first app” links to consolidated slug with `?lang=`.
src/frontend/src/content/docs/ja/get-started/app-host.mdx	Updates Japanese “first app” links to consolidated slug with `?lang=`.
src/frontend/src/content/docs/extensibility/multi-language-integration-authoring.mdx	Updates TypeScript “first app” link to consolidated slug.
src/frontend/src/content/docs/architecture/resource-model.mdx	Updates TypeScript “first app” link to consolidated slug.
src/frontend/src/content/docs/architecture/multi-language-architecture.mdx	Updates TypeScript “first app” link to consolidated slug.
src/frontend/src/content/docs/dashboard/standalone.mdx	Updates samples repo org.
src/frontend/src/content/docs/dashboard/standalone-for-python.mdx	Updates “first app/deploy” consolidated links for Python path.
src/frontend/src/content/docs/community/contributors.mdx	Updates repo stats widgets to microsoft/aspire-samples.
src/frontend/src/content/docs/community/contributor-guide.mdx	Adds conventions for Aspire language selectors and callout syntax guidance.
src/frontend/src/content/docs/integrations/reverse-proxies/yarp.mdx	Updates Aspire repo link to microsoft org.
src/frontend/src/content/docs/integrations/databases/efcore/seed-database.mdx	Updates samples org in link.
src/frontend/src/content/docs/integrations/databases/efcore/migrations.mdx	Updates Learn sample URL owner path.
src/frontend/src/content/docs/integrations/custom-integrations/client-integrations.mdx	Updates samples repo org for health checks UI sample link.
src/frontend/src/content/docs/deployment/pipelines.mdx	Adds Aspire language PivotSelector + Pivot blocks for language-specific content.
src/frontend/src/content/docs/deployment/kubernetes.mdx	Updates code tabs to `syncKey='aspire-lang'` and simplifies imports.
src/frontend/src/content/docs/deployment/javascript-apps.mdx	Updates code tabs to `syncKey='aspire-lang'` and formatting.
src/frontend/src/content/docs/deployment/docker-compose.mdx	Updates code tabs to `syncKey='aspire-lang'` and adds TS “not yet available” notes where relevant.
src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx	Updates code tabs to `syncKey='aspire-lang'` and TS availability notes.
src/frontend/src/content/docs/deployment/azure/azure-developer-cli.mdx	Adds Aspire language PivotSelector + Pivot blocks for `withAzdResourceNaming` example.
src/frontend/src/content/docs/app-host/withdockerfile.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/typescript-apphost.mdx	Updates “first app” link to consolidated slug.
src/frontend/src/content/docs/app-host/persistent-containers.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/executable-resources.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/eventing.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/container-registry.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/container-files.mdx	Updates code tabs to `syncKey='aspire-lang'`.
src/frontend/src/content/docs/app-host/configuration.mdx	Adds Aspire language PivotSelector + Pivot blocks for launch-profile/config differences.
src/frontend/src/content/docs/app-host/certificate-configuration.mdx	Updates code tabs to `syncKey='aspire-lang'` and adds TS “not yet available” slots.
src/frontend/src/content/docs/get-started/first-app-typescript-apphost.mdx	Removes legacy TS-specific quickstart page (replaced by unified first-app flow).
src/frontend/src/components/starlight/PageTitle.astro	Tags page actions container as a tour target.
src/frontend/src/components/starlight/Header.astro	Adds tour help trigger; marks key header controls as tour targets; responsive tweaks.
src/frontend/src/components/starlight/Head.astro	Adds SiteTour injection and pre-paint restoration for sidebar/apphost language state.
src/frontend/src/components/starlight/EditLink.astro	Wraps edit link with tour target; adjusts translation call typing.
src/frontend/src/components/PivotSelector.astro	Marks selector and collapse/expand buttons as tour targets.
src/frontend/src/components/IntegrationGrid.astro	CSS containment/overflow tweaks to avoid layout/scroll issues in infinite rows.
src/frontend/src/components/InstallCliModal.astro	Supports multiple open buttons and rebind guard; extracts shared `openModal` logic.
src/frontend/src/components/FooterSocials.astro	Adds mobile footer tool buttons for cookies/CLI; marks as tour targets.
src/frontend/src/components/FooterPreferences.astro	Marks footer preferences as tour target; TS typing adjustment for userAgentData access.
src/frontend/src/components/AppHostLangPivot.astro	Adds new component to swap AppHost content based on global `data-apphost-lang`.
src/frontend/src/assets/icons/site-nav-help.svg	Adds new icon asset for tour help button.
src/frontend/scripts/update-samples.js	Updates samples fetch script to microsoft/aspire-samples.
src/frontend/scripts/update-github-stats.js	Updates tracked repos list to microsoft/aspire-samples.
src/frontend/config/sidebar/integrations.topics.ts	Reorganizes sidebar framework items (adds JS subgroup; moves WPF/Orleans into .NET grouping).
src/frontend/config/sidebar/docs.topics.ts	Updates docs topic label and consolidates first-app/deploy/existing-app entries to single slugs.
src/frontend/config/redirects.mjs	Adds redirects from split AppHost getting-started slugs to consolidated routes (incl. /ja).
src/frontend/config/head.attrs.ts	Updates analytics script sources to new public paths.
.github/skills/update-samples/SKILL.md	Updates skill docs to refer to microsoft/aspire-samples.
.github/skills/doc-writer/SKILL.md	Updates doc-writing guidance to prefer fenced callouts and introduces AppHostLangPivot guidance.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-02T21:23:00Z

src/frontend/src/components/starlight/Head.astro

+    opacity: 0;
+  }
+</style>
+


The site tour “paint lock” hides the entire page body (opacity: 0) until JS clears data-site-tour-pending. This can noticeably delay first paint (blank page until DOMContentLoaded) and can leave the page invisible if the SiteTour script fails to run. Consider avoiding hiding the full body (or add a short timeout fallback to clear the attribute).

Suggested change

<script is:inline>

(function () {

function clearSiteTourPending() {

document.documentElement.removeAttribute('data-site-tour-pending');

}

setTimeout(clearSiteTourPending, 150);

if (document.readyState === 'loading') {

document.addEventListener('DOMContentLoaded', clearSiteTourPending, { once: true });

} else {

clearSiteTourPending();

}

})();

</script>

Copilot · 2026-04-02T21:23:00Z

src/frontend/src/components/starlight/Head.astro

+      var rawAppHostLang =
+        localStorage.getItem('aspire-lang') ||
+        localStorage.getItem('aspire-apphost-lang') ||
+        localStorage.getItem('starlight-synced-tabs__apphost-lang') ||
+        localStorage.getItem('starlight-synced-tabs__apphost-implementation-lang') ||
+        'csharp';
+      var appHostLang = normalizeAppHostLang(rawAppHostLang) || 'csharp';
+      document.documentElement.setAttribute('data-apphost-lang', appHostLang);


rawAppHostLang doesn’t consider the new synced-tab storage key starlight-synced-tabs__aspire-lang. Since many pages now use <Tabs syncKey='aspire-lang'>, users can end up with tabs set to TypeScript while data-apphost-lang stays on the default (csharp). Add starlight-synced-tabs__aspire-lang as a fallback (and/or mirror it into aspire-lang) so AppHostLangPivot + pivots stay in sync.

Copilot · 2026-04-02T21:23:01Z

src/frontend/src/content/docs/get-started/prerequisites.mdx

+    :::note[Visual Studio Code]{icon="vscode"}
    We recommend [Visual Studio Code](https://code.visualstudio.com/) for the best experience—a lightweight, cross-platform code editor with excellent Aspire support. Install the following extensions to get started:

-    <Steps>
-
-    1. [Aspire extension](/get-started/aspire-vscode-extension/) for Aspire-specific commands and features.
-
-    </Steps>
+    [Aspire extension](/get-started/aspire-vscode-extension/) for Aspire-specific commands and features.

    <Pivot id="csharp">

    Additionally, install the [C# extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) for C# language support.

    </Pivot>
-    </Aside>
+    :::


This page removed the AppHost language PivotSelector, but it still contains Pivot id="csharp" blocks later in the flow. Without an active PivotSelector, those blocks won’t be gated and will render for all readers (including TypeScript), which makes the IDE guidance inaccurate. Either reintroduce a single PivotSelector for the page or replace these Pivot blocks with the new Tabs syncKey='aspire-lang' pattern.

Copilot · 2026-04-02T21:23:01Z

tmp/aspire-lang-margin-patches/patch-1.txt

+*** Begin Patch
+*** Update File: D:/GitHub/aspire.dev/src/frontend/src/content/docs/app-host/certificate-configuration.mdx
+@@
+
+<PivotSelector


This looks like a local patch artifact (paths to D:/GitHub/... and *** Begin Patch markers). It shouldn’t be committed to the repo; please remove this file from the PR.

Copilot · 2026-04-02T21:23:01Z

tmp/aspire-lang-margin-patches/patch-2.txt

+*** Begin Patch
+*** Update File: D:/GitHub/aspire.dev/src/frontend/src/content/docs/app-host/executable-resources.mdx
+@@
+
+<PivotSelector


This looks like a local patch artifact (paths to D:/GitHub/... and *** Begin Patch markers). It shouldn’t be committed to the repo; please remove this file from the PR.

Copilot · 2026-04-02T21:23:01Z

tmp/aspire-lang-margin-patches/patch-3.txt

+*** Begin Patch
+*** Update File: D:/GitHub/aspire.dev/src/frontend/src/content/docs/deployment/azure/customize-container-apps.mdx
+@@
+
+<PivotSelector


This looks like a local patch artifact (paths to D:/GitHub/... and *** Begin Patch markers). It shouldn’t be committed to the repo; please remove this file from the PR.

Copilot · 2026-04-02T21:23:02Z

tmp/aspire-lang-margin-patches/patch-4.txt

+*** Begin Patch
+*** Update File: D:/GitHub/aspire.dev/src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx
+@@
+
+<PivotSelector


This looks like a local patch artifact (paths to D:/GitHub/... and *** Begin Patch markers). It shouldn’t be committed to the repo; please remove this file from the PR.

Copilot · 2026-04-02T21:23:02Z

tmp/aspire-lang-margin-patches/patch-5.txt

+*** Begin Patch
+*** Update File: D:\GitHub\aspire.dev/src\frontend\src\content\docs\ja\get-started\what-is-aspire.mdx
+@@
+
+<PivotSelector


This looks like a local patch artifact (paths to D:\GitHub\... and *** Begin Patch markers). It shouldn’t be committed to the repo; please remove this file from the PR.

IEvangelist added 10 commits April 1, 2026 11:42

fix: Correct markdown syntax for code blocks in contributor guide

be9ce94

Refactor code structure for improved readability and maintainability

4e9108c

fix: Update references from dotnet to microsoft for aspire-samples re…

81b30e2

…pository

style: Enhance sidebar and integration grid styles for improved layou…

0675ce5

…t and usability

fix: Update route data handling and normalize path function for bread…

839bd60

…crumbs

chore: rewrite add existing app for scenarios, avoiding bias.

4ecee41

Copilot AI review requested due to automatic review settings April 2, 2026 21:14

IEvangelist requested review from JamesNK, aaronpowell and eerhardt as code owners April 2, 2026 21:14

Copilot started reviewing on behalf of IEvangelist April 2, 2026 21:15 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor AppHost docs and add a localized site tour#666

Refactor AppHost docs and add a localized site tour#666
IEvangelist wants to merge 10 commits intomainfrom
dapine/apphost-selector-refactor

IEvangelist commented Apr 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

+<script is:inline>
+  (function () {
+    function clearSiteTourPending() {
+      document.documentElement.removeAttribute('data-site-tour-pending');
+    }
+    setTimeout(clearSiteTourPending, 150);
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', clearSiteTourPending, { once: true });
+    } else {
+      clearSiteTourPending();
+    }
+  })();
+</script>

Conversation

IEvangelist commented Apr 2, 2026

Summary

More detail

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants