Improve search discoverability and agent-readable content - #1633
Open
David Pine (IEvangelist) wants to merge 3 commits into
Open
Improve search discoverability and agent-readable content#1633David Pine (IEvangelist) wants to merge 3 commits into
David Pine (IEvangelist) wants to merge 3 commits into
Conversation
Restore page-specific descriptions, publish useful homepage Markdown, strengthen observability guidance, and defer inactive AppHost examples. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist)
requested a review
from James Newton-King (JamesNK)
as a code owner
September 9, 2026 13:41
Copilot started reviewing on behalf of
David Pine (IEvangelist)
September 9, 2026 13:42
View session
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
It introduces broad build-time output rewriting (homepage Markdown + deferred example payload emission) alongside runtime lazy-loading and extensive docs/metadata changes that warrant final human review.
Pull request overview
This PR improves aspire.dev’s search/SEO discoverability and “agent-readable” content by restoring per-page descriptions with a Starlight fallback, generating substantive homepage Markdown companions, and making observability + agent debugging guidance easier to find—while also reducing homepage HTML by deferring inactive AppHost examples into a shared lazy-loaded payload.
Changes:
- Add build-time homepage post-processing: render localized homepage Markdown companions and defer inactive AppHost examples into a content-addressed
_astro/apphost-examples.*.htmlpayload. - Update homepage UI + i18n to surface direct links to dashboard/telemetry/agent debugging content and add localized error messaging for deferred examples.
- Expand/adjust unit + Playwright coverage for metadata, locale fallbacks, homepage Markdown negotiation, and deferred-example loading/retry behavior.
File summaries
| File | Description |
|---|---|
| src/frontend/tests/unit/homepage-markdown.vitest.test.ts | Adds unit coverage for homepage HTML → Markdown conversion and build integration finalization. |
| src/frontend/tests/unit/apphost-examples.vitest.test.ts | Adds unit coverage for extracting/defering AppHost examples into a hashed static payload. |
| src/frontend/tests/e2e/og-metadata.spec.ts | Extends e2e coverage for per-page descriptions, OG metadata, canonicals, and locale fallbacks. |
| src/frontend/tests/e2e/homepage.spec.ts | Verifies new homepage observability/agent link set and URLs. |
| src/frontend/tests/e2e/custom-components.spec.ts | Adds e2e coverage for deferred AppHost examples loading, retry behavior, and “latest selection wins” during async load. |
| src/frontend/tests/e2e/api-markdown-routes.spec.ts | Adds CI-only checks that homepage companion Markdown routes publish useful Markdown. |
| src/frontend/src/utils/page-metadata.ts | Clarifies OG/Twitter fallback description semantics and intended ownership vs Starlight meta. |
| src/frontend/src/content/i18n/en.json | Updates observability copy and adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/da.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/de.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/es.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/fr.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/hi.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/id.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/it.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/ja.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/ko.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/pt-BR.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/ru.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/tr.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/uk.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/i18n/zh-CN.json | Adds new observability link labels + AppHost examples error string. |
| src/frontend/src/content/docs/get-started/aspire-mcp-server.mdx | Reframes MCP server doc around application observability for coding agents and adds cross-links. |
| src/frontend/src/content/docs/get-started/ai-coding-agents.mdx | Refocuses agent setup guidance on observability evidence and adds a worked-debugging pointer. |
| src/frontend/src/content/docs/fundamentals/telemetry.mdx | Expands OpenTelemetry/distributed tracing concepts and clarifies instrumentation vs orchestration. |
| src/frontend/src/content/docs/dashboard/standalone.mdx | Repositions standalone dashboard as an OTLP viewer and clarifies limitations without AppHost. |
| src/frontend/src/content/docs/dashboard/standalone-for-python.mdx | Tightens Python standalone dashboard framing and adds clarification/cross-links for request vs log semantics. |
| src/frontend/src/content/docs/dashboard/standalone-for-nodejs.mdx | Tightens Node.js telemetry tutorial framing and clarifies log export vs console output. |
| src/frontend/src/content/docs/dashboard/overview.mdx | Reframes dashboard overview around local OpenTelemetry + AppHost resource capabilities. |
| src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx | Adds a worked investigation walkthrough using a pinned Python sample and updates standalone auth guidance. |
| src/frontend/src/content/docs/app-host/migrate-from-docker-compose.mdx | Updates Compose vs Aspire comparison to include observability + standalone dashboard positioning. |
| src/frontend/src/components/home/HomePage.astro | Replaces single dashboard link with a set of observability/agent links and updates layout styles. |
| src/frontend/src/components/AppHostBuilder.client.ts | Adds lazy-loading of deferred AppHost examples and adjusts interaction handling while loading. |
| src/frontend/src/components/AppHostBuilder.astro | Adds localized data-examples-error attribute for client-side load failures. |
| src/frontend/config/homepage-markdown.mjs | New HTML→Markdown converter for homepage authored content (strips decorative UI, preserves meaningful examples/links). |
| src/frontend/config/head.attrs.ts | Removes the hard-coded global meta description so Starlight/page frontmatter can own descriptions. |
| src/frontend/config/aspire-version-placeholders-integration.mjs | Extends post-build hook to finalize homepage Markdown companions and emit deferred AppHost example payload. |
| src/frontend/config/apphost-examples.mjs | New build-time transformer to extract and content-address AppHost example HTML and inject lazy-load pointer. |
| src/frontend/astro.config.mjs | Centralizes site description and wires it into Starlight + llms-txt plugin configuration. |
Review details
- Files reviewed: 39/39 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Tighten spacing in the expanded observability section so the production mobile viewport remains within the existing compactness gate. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Document authenticated standalone MCP with an explicit API key and keep deferred AppHost examples out of the homepage Pagefind index. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
David Pine (IEvangelist)
requested a review
from Mitch Denny (mitchdenny)
as a code owner
September 9, 2026 21:11
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
Validation
pnpm lintNotes
Addresses #1624.