fix(docs): restore GitHub Pages assets and navigation

[Wassim Chegham (manekinekko)]

Summary

The published docs at https://microsoft.github.io/scope/ were built for an isolated Pages hostname with no /scope base path. Stylesheets and scripts loaded from the wrong location, and 177 internal URLs omitted the deployment prefix.

• Build both pull requests and production with the public origin and /scope base instead of the URL reported by actions/configure-pages.
• Prefix internal Markdown links, reference definitions, images, and literal MDX href/src attributes at build time. Preserve external URLs, relative links, fragments, code examples, and local root deployments.
• Replace links to the nonexistent /reference/api/operations/ index with /reference/api/.
• Add plugin regression tests to the Pages workflow and document deployment and link-authoring conventions.

Demo

Documentation-site fix only; no Portal or CLI changes. Before: assets under https://microsoft.github.io/_astro/ returned 404, although the same assets existed under /scope/_astro/. The rebuilt site uses /scope/ for assets and navigation. The public site will update after merge and deployment.

Testing

• cd website && pnpm test: all 7 plugin regression tests passed.
• SITE=https://microsoft.github.io BASE_PATH=/scope pnpm run build: 200 pages generated.
• Built separately with BASE_PATH=/: 200 pages generated, preserving local root deployment behavior.
• Checked all 42,476 local asset and link URLs in each build: every target exists; the public build has no missing /scope/ prefixes. Public canonical and sitemap URLs use https://microsoft.github.io/scope/.
• Local production preview serves both /scope/ and /scope/reference/api/ successfully.

Documentation and compatibility

Updated website/README.md and website/AGENTS.md with the public deployment settings, base-aware link conventions, and plugin test command. No API, CLI, database, or dependency changes. Local development still defaults to /.

Checklist

• If Portal features changed, keep CLI capabilities in sync. N/A: no Portal feature changes.
• If Portal components changed, update their Storybook stories. N/A: no Portal component changes.
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. N/A: no database changes.
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. N/A: no dependency changes.

[Copilot]

🟢 Approval recommended

The base-path implementation is covered by regression tests and the deployment, documentation, and API-link changes are consistent.

Pull request overview

Restores correct GitHub Pages asset and navigation URLs for the /scope deployment.

Changes:

• Adds base-path rewriting for Markdown and MDX URLs with regression tests.
• Updates API reference links and documentation authoring guidance.
• Configures CI builds with the public GitHub Pages origin and base path.

File summaries

File	Description
website/src/plugins/remark-base-path.mjs	Adds deployment base-path rewriting.
website/src/plugins/remark-base-path.test.mjs	Tests URL transformation behavior.
website/astro.config.mjs	Registers the plugin and base configuration.
.github/workflows/static.yml	Builds and tests using public Pages settings.
website/package.json	Adds the plugin test command.
website/README.md	Documents link and deployment conventions.
website/AGENTS.md	Updates site development guidance.
website/src/content/docs/resources/faq.md	Corrects API reference link.
website/src/content/docs/reference/rest-api.md	Corrects API reference links.
website/src/content/docs/guides/submitting-requests-api.mdx	Corrects API reference links.
website/src/content/docs/guides/prioritizing-requests.mdx	Corrects API reference link.

Review details

• Files reviewed: 11/11 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.