Fix direct navigation 404 on Blazor sample pages (#369)

* Initial plan

* Fix 404 when navigating directly to a Blazor sample page

Co-authored-by: mattleibow <1096616+mattleibow@users.noreply.github.com>

* Update comment job to fire on synchronize and update existing comment

Co-authored-by: mattleibow <1096616+mattleibow@users.noreply.github.com>

* Copy root 404.html during staging deploys so SPA redirect works for staging paths

Co-authored-by: mattleibow <1096616+mattleibow@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: mattleibow <1096616+mattleibow@users.noreply.github.com>

Author: Copilot

.github/workflows/docs-deploy.yml

@@ -181,14 +181,19 @@ jobs:
           mkdir -p staging/$PR_NUMBER
           rm -rf staging/$PR_NUMBER/*
           cp -r /tmp/site-temp/. staging/$PR_NUMBER/
+
+          # Copy 404.html to the gh-pages root so SPA redirects work for staging
+          # paths (GitHub Pages only serves the root-level 404.html for missing paths)
+          cp /tmp/site-temp/404.html 404.html
+
           rm -rf /tmp/site-temp
 
           # Ensure .nojekyll exists at root so _framework is served
           touch .nojekyll
 
           git config --local user.email "action@github.com"
           git config --local user.name "GitHub Action"
-          git add .nojekyll staging/$PR_NUMBER
+          git add .nojekyll 404.html staging/$PR_NUMBER
           if ! git diff --cached --quiet; then
             git commit -m "Deploy staging docs for PR #$PR_NUMBER"
             git push origin gh-pages
@@ -199,7 +204,7 @@ jobs:
   comment:
     runs-on: ubuntu-latest
     needs: [build, deploy]
-    if: needs.build.outputs.is_staging == 'true' && (github.event.action == 'opened' || github.event.action == 'reopened')
+    if: needs.build.outputs.is_staging == 'true' && (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize')
     permissions:
       pull-requests: write
     steps:
@@ -211,21 +216,6 @@ jobs:
             const stagingUrl = `https://mono.github.io/SkiaSharp.Extended/staging/${prNumber}/`;
             const sampleUrl = `https://mono.github.io/SkiaSharp.Extended/staging/${prNumber}/sample/`;
 
-            // Only comment once; check for an existing bot comment to avoid duplicates on reopen
-            const comments = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: prNumber
-            });
-            const botComment = comments.data.find(c =>
-              c.user.type === 'Bot' &&
-              c.body.includes('Documentation Preview')
-            );
-            if (botComment) {
-              console.log('Bot comment already exists, skipping.');
-              return;
-            }
-
             const commentBody = [
               '📖 **Documentation Preview**',
               '',
@@ -241,9 +231,28 @@ jobs:
               '*This comment is automatically updated by the documentation staging workflow.*'
             ].join('\n');
 
-            await github.rest.issues.createComment({
+            // Update existing bot comment if present, otherwise create a new one
+            const comments = await github.rest.issues.listComments({
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: prNumber,
-              body: commentBody
+              issue_number: prNumber
             });
+            const botComment = comments.data.find(c =>
+              c.user.type === 'Bot' &&
+              c.body.includes('Documentation Preview')
+            );
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: commentBody
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body: commentBody
+              });
+            }

docs/404.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <title>SkiaSharp Extended - Page Not Found</title>
+    <script>
+        // GitHub Pages SPA redirect: when a user navigates directly to a Blazor sample
+        // sub-page, GitHub Pages serves this 404.html. If the path is under a /sample/
+        // segment, redirect to that sample's index.html with the path encoded in the
+        // query string so that the Blazor router can restore the correct route.
+        (function () {
+            var l = window.location;
+            var pathParts = l.pathname.split('/');
+            var sampleIdx = pathParts.indexOf('sample');
+            if (sampleIdx !== -1 && sampleIdx < pathParts.length - 1 && pathParts[sampleIdx + 1] !== '') {
+                var basePath = pathParts.slice(0, sampleIdx + 1).join('/');
+                var remaining = pathParts.slice(sampleIdx + 1).join('/').replace(/&/g, '~and~');
+                l.replace(
+                    l.protocol + '//' + l.hostname + (l.port ? ':' + l.port : '') +
+                    basePath + '/?/' + remaining +
+                    (l.search ? '&' + l.search.slice(1).replace(/&/g, '~and~') : '') +
+                    l.hash
+                );
+            }
+        })();
+    </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>
+</body>
+</html>

docs/docfx.json

@@ -30,7 +30,8 @@
     "resource": [
       {
         "files": [
-          "images/**"
+          "images/**",
+          "404.html"
         ]
       }
     ],