Refactor AppHost docs and add a localized site tour#666
Merged
IEvangelist merged 25 commits intomainfrom Apr 7, 2026
Merged
Conversation
IEvangelist
requested review from
JamesNK,
aaronpowell and
eerhardt
as code owners
Contributor
There was a problem hiding this comment.
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.
IEvangelist
force-pushed
the
dapine/apphost-selector-refactor
branch
from
4ecee41 to
f2d6c27
Compare
- 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.
- 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.
- 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.
- Refactored getContentBreadcrumbs function for cleaner syntax. - Added functionality to dismiss site tour consent if visible in e2e tests. - Implemented waitForTopicSidebarReady helper to ensure topic sidebar is ready before interactions. - Created tests for topic sidebar controls, ensuring they persist state and respond correctly to user actions. - Added checks for sidebar collapse state and filter reset on reload.
- Implemented a new end-to-end test for the site tour feature in `site-tour.spec.ts`, covering scenarios such as opening the tour, resuming progress, and completing the tour on larger screens. - Added a test to ensure the site tour is disabled on narrow viewports. - Created unit tests in `site-tour.vitest.test.ts` for various helper functions related to site tour step definitions, state parsing, and filtering logic. - Verified the correct order of site tour steps and ensured proper handling of malformed stored states.
…stency test: refactor pivot selector tests to improve clarity and maintain state
…ith cookie consent handling
…ction and enhance clarity
IEvangelist
force-pushed
the
dapine/apphost-selector-refactor
branch
from
7a23813 to
7bab4cf
Compare
…ss in mobile view
Member
|
I'm not a fan of some of the changes:
|
Member
Author
Yeah, this one is tough. It's difficult architecting how to structure, organize, present, and expose all the content. This is the direction we're leaning now - but that might change.
One is a site-wide search, and the other is a filter. They're different and that UX is common, github.com even has it for example. The collapsible sidebar is too: 
They're easy to dismiss, but helpful when you need them. Also, one thing is certain after watching replays of user studies, most readers do not know how to use the site...maybe it's just something that we take for granted? |
Member
I think the difference is in GitHub you're filtering on content inside a PR which is valid. IMO the only use case for search in aspire.dev is to find docs on a topic. And that can be achieved with one search box. Sometimes less is more. And a problem with the filter sidebar is it only filters pages in the current section. e.g. if you're viewing Fundamentals and type in dashboard, you get no results. Collapsing the sidebar in a PR is useful because you can see more code (although personally I never use it). Collapsing the sidebar in the docs site doesn't allow you to view more docs because there is a max width.
I still think it's a horrible first impression. I've never seen a dev tool site start a tour when I visit its docs. It's what I'd expect when I launch an expense or travel app. |
maddymontaquila
approved these changes
Apr 7, 2026
Contributor
maddymontaquila
left a comment
maddymontaquila
left a comment
There was a problem hiding this comment.
just went htorugh both get starteds and it looks good!! I do like the site tour but I dont think it should pop up automatically - or maybe we run a study or a/b test on it - mostly because it interrupted my flow and I was like UGH A POPUP
Member
Author
I just toggled it off in an earlier commit, hid it behind the feature flag all up. So, while it could be enabled - it will ship off (hidden) by default. If you want, I could remove that, and instead change the behavior to not automatically show. Only manually selecting the icon would show the tour. Thoughts? |
JamesNK
pushed a commit
that referenced
this pull request
Apr 16, 2026
* feat: Refactor AppHost language pivot component and update documentation - 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. * fix: Correct markdown syntax for code blocks in contributor guide * feat(tour): implement site tour functionality with step definitions and 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. * Refactor code structure for improved readability and maintainability * fix: Update references from dotnet to microsoft for aspire-samples repository * Add analytics tracking scripts for event capturing - 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. * style: Enhance sidebar and integration grid styles for improved layout and usability * fix: Update route data handling and normalize path function for breadcrumbs * Add site tour translations for multiple languages - 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. * chore: rewrite add existing app for scenarios, avoiding bias. * chore: add `tmp/` to .gitignore and delete patches. * feat: enhance sidebar functionality and improve breadcrumb utility - Refactored getContentBreadcrumbs function for cleaner syntax. - Added functionality to dismiss site tour consent if visible in e2e tests. - Implemented waitForTopicSidebarReady helper to ensure topic sidebar is ready before interactions. - Created tests for topic sidebar controls, ensuring they persist state and respond correctly to user actions. - Added checks for sidebar collapse state and filter reset on reload. * Add end-to-end and unit tests for site tour functionality - Implemented a new end-to-end test for the site tour feature in `site-tour.spec.ts`, covering scenarios such as opening the tour, resuming progress, and completing the tour on larger screens. - Added a test to ensure the site tour is disabled on narrow viewports. - Created unit tests in `site-tour.vitest.test.ts` for various helper functions related to site tour step definitions, state parsing, and filtering logic. - Verified the correct order of site tour steps and ensured proper handling of malformed stored states. * fix: update footer preferences heading to use paragraph tag for consistency test: refactor pivot selector tests to improve clarity and maintain state * fix: rename variables for site tour props to avoid conflicts * fix: update documentation and styles for improved clarity and consistency * fix: improve inline code handling in markdown content for better readability * fix: remove unnecessary 'prev' field from documentation for clarity * fix: refactor Playwright configuration and enhance E2E test support with cookie consent handling * fix: refactor prerequisites documentation to streamline language selection and enhance clarity * fix: refactor TypeScript API routes and enhance slug generation for better uniqueness * fix: update links in documentation for consistency and clarity * fix: remove inline-block display from code elements for better wrapping behavior * fix: enhance header actions for better accessibility and responsiveness in mobile view * fix: refactor site tour feature to enable/disable based on environment variable
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Also fixes: #229 & #230
More detail
AppHostLangPivot.astroand reworked documentation to reduce C#/TypeScript duplication while keeping AppHost-specific implementation details in tabs.SiteTour.astro, tour trigger/help affordances, footer preferences targeting, localized copy inen.jsonplus the non-English locale files, and the supporting header/sidebar/head integration changes.1ds.jsandtrack.jsfrom page-level sources intopublic/scripts/analytics/and updated the site to use the new script locations.Testing