Fix direct navigation 404 on Blazor sample pages

[Copilot]

GitHub Pages only serves the root-level 404.html for all missing paths — subdirectory 404.html files are never invoked. The existing SPA redirect handler lived at docs/_site/sample/404.html and was never reached, so direct navigation to any sample route (e.g. /SkiaSharp.Extended/sample/shapes) returned GitHub's default 404.

Changes

• docs/404.html — new root-level 404 page with an inline SPA redirect script. Dynamically detects the sample segment in the URL path, then encodes the remaining route as a query string and redirects to that sample's index.html. Works for both main and staging deployments without hardcoded segment counts:

  • Main: /SkiaSharp.Extended/sample/shapes → /SkiaSharp.Extended/sample/?/shapes
  • Staging: /SkiaSharp.Extended/staging/42/sample/shapes → /SkiaSharp.Extended/staging/42/sample/?/shapes
  • Non-sample 404s fall through to a plain "Page Not Found" message.

• docs/docfx.json — added 404.html to the resource files so docfx copies it to _site/ (and thus to the gh-pages root) during every build.

• .github/workflows/docs-deploy.yml — two improvements to the staging workflow:

  • The comment job now also runs on synchronize events (new commits pushed to the PR), matching the deploy job behavior. The script updates an existing bot comment rather than skipping, so the staging preview link is always refreshed after each push.
  • The staging deploy step now copies 404.html to the gh-pages root in addition to staging/$PR_NUMBER/. Because GitHub Pages only serves the root-level 404.html for all missing paths, staging deep-links (e.g. /SkiaSharp.Extended/staging/369/sample/shapes) would otherwise never trigger the SPA redirect — they now work correctly as soon as a staging deployment completes.

The complementary decode script already in sample/index.html reads the encoded query string and restores the correct URL before the Blazor router initializes — no changes needed there.

Original prompt

When navigating directly to a sample page in the browser, I get a 404.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[mattleibow]

@copilot i see the docs comment was not posted because the way things work. Can we update the yaml to also fire the comment update after a commit just like we have it deploy the code.

[Copilot]

@copilot i see the docs comment was not posted because the way things work. Can we update the yaml to also fire the comment update after a commit just like we have it deploy the code.

Done in a6c6551. The comment job condition now includes synchronize, and the script logic is updated to updateComment on the existing bot comment when one is found (rather than skipping), or createComment if none exists yet.

[github-actions]

📖 Documentation Preview

The documentation for this PR has been deployed and is available at:

🔗 View Staging Documentation

🔗 View Staging Blazor Sample

This preview will be updated automatically when you push new commits to this PR.

---

This comment is automatically updated by the documentation staging workflow.

[mattleibow]

@copilot can you see why this is not working https://mono.github.io/SkiaSharp.Extended/staging/369/sample/shapes

[Copilot]

@copilot can you see why this is not working https://mono.github.io/SkiaSharp.Extended/staging/369/sample/shapes

The root cause: GitHub Pages only serves the root-level 404.html for all missing paths. The staging deploy job was only writing to staging/369/ — it never placed 404.html at the gh-pages root, so there was nothing to intercept the 404 and do the SPA redirect.

Fixed in fda9852: the staging deploy step now also copies 404.html to the gh-pages root (git add .nojekyll 404.html staging/$PR_NUMBER). Once this PR's next CI run deploys, the root 404.html will be in place and navigating directly to staging Blazor routes like /SkiaSharp.Extended/staging/369/sample/shapes will redirect correctly.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• mono.github.io
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

Fixes GitHub Pages deep-link 404s for the Blazor sample by ensuring a root-level SPA redirect 404.html is deployed (since GitHub Pages only serves the repository-root 404), and improves the staging preview PR comment behavior.

Changes:

• Add a new root docs/404.html with an inline SPA redirect script for /sample/... routes.
• Ensure docs/404.html is included in DocFX resources so it’s published to the site output.
• Update the docs deploy workflow to (a) copy 404.html to the gh-pages root for staging and (b) update an existing staging preview PR comment on new commits.

Reviewed changes

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

File	Description
docs/docfx.json	Adds 404.html to DocFX resource files so it gets copied into _site/ during builds.
docs/404.html	Introduces a root-level GitHub Pages SPA redirect handler for Blazor sample deep-links.
.github/workflows/docs-deploy.yml	Copies root 404.html during staging deploys and updates/refreshes the staging preview PR comment on synchronize.

[Copilot]

The staging deploy step copies the built 404.html into the gh-pages root. This means every staging deployment can overwrite the root 404 used by the main docs site, temporarily changing production 404 behavior until the next main deploy. Consider avoiding mutating the root 404 on staging runs (or only doing it when the staged 404 is identical to the current root file), so staging previews don't affect the main site.

[Copilot]

github.rest.issues.listComments is called without pagination settings. If a PR has >30 comments, the existing workflow bot comment may not be returned and the job will create a duplicate instead of updating the original. Use pagination (e.g., per_page: 100 and/or github.paginate) when searching for the existing bot comment.

[Copilot]

The non-sample fallback link is hardcoded to /SkiaSharp.Extended/. On staging URLs (e.g. /SkiaSharp.Extended/staging/<pr>/...), this sends users to the main docs instead of the staging preview. Consider making this link relative (e.g. to the current site root) or computing the correct base path from window.location.pathname so it works consistently in both main and staging.

Suggested change

	})();
	</script>
	</head>
	<body>
	<h1>Page Not Found</h1>
	<p>The page you are looking for does not exist.</p>
	<p><a href="/SkiaSharp.Extended/">Go to the documentation</a></p>
	// Compute the base documentation path so the fallback link works on both
	// the main site (/SkiaSharp.Extended/...) and staging URLs
	// (/SkiaSharp.Extended/staging/<pr>/...).
	function getDocsBasePath() {
	var parts = l.pathname.split('/');
	var extendedIndex = parts.indexOf('SkiaSharp.Extended');
	if (extendedIndex === -1) {
	// Fallback if the expected segment is not present.
	return '/';
	}
	// Start with /SkiaSharp.Extended/
	var endIndex = extendedIndex + 2; // include 'SkiaSharp.Extended'
	// If this is a staging URL like /SkiaSharp.Extended/staging/<pr>/...,
	// include the staging and PR segments as part of the base path.
	if (parts[extendedIndex + 1] === 'staging' && parts.length > extendedIndex + 2) {
	endIndex = extendedIndex + 3;
	}
	var base = parts.slice(0, endIndex).join('/');
	if (base === '') {
	base = '/';
	}
	// Ensure a trailing slash for consistency.
	if (base.charAt(base.length - 1) !== '/') {
	base += '/';
	}
	return base;
	}
	window.addEventListener('DOMContentLoaded', function () {
	var link = document.getElementById('docs-link');
	if (!link) {
	return;
	}
	link.href = getDocsBasePath();
	});
	})();
	</script>
	</head>
	<body>
	<h1>Page Not Found</h1>
	<p>The page you are looking for does not exist.</p>
	<p><a id="docs-link" href="#">Go to the documentation</a></p>