commit - 6ba38ae10335c72e26d9cebfa9a7d473742b2a47
commit + a91743def7ed40e47ad2d68dc75a967b2b2e9a7c
blob - ec93827f5e49d90529a215fda6d88b9f8f3170e8
blob + 4186bc49d526012265b947dab29441dd67ef4afe
--- docs/make.jl
+++ docs/make.jl
@@ -52,21 +52,25 @@ makedocs(;
     ],
 )
 
+# GitHub's default Jekyll processing on a branch-based Pages deploy
+# silently ignores any path starting with `_` — the standard reason any
+# non-Jekyll static site on GitHub Pages needs a `.nojekyll` marker.
 # DocumenterVitepress has the code for this (writer.jl, `touch(...,
 # "final_site", ".nojekyll")`) but it's commented out in the installed
-# version (0.3.5) — confirmed by reading the package source, not assumed
-# — so gh-pages currently has no .nojekyll at all. Nothing has broken
-# from this yet (verified: the live site serves correctly), but GitHub's
-# default Jekyll processing on a branch-based Pages deploy silently
-# ignores any path starting with `_`, which is exactly the kind of thing
-# a future Vitepress internal-asset naming convention could introduce —
-# added here rather than relying on that staying true by luck. One file
-# per built base's own root (`docs/build/<n>/`, one per version — "1" for
-# "dev" right now, more once tags exist) since that's what deploydocs
-# actually publishes as each version's own directory in gh-pages.
-for dir in filter(isdir, readdir(joinpath(@__DIR__, "build"); join=true))
-    isfile(joinpath(dir, "index.html")) && touch(joinpath(dir, ".nojekyll"))
-end
+# version (0.3.5) — confirmed by reading the package source, not assumed.
+# A first attempt here touched `.nojekyll` into each `docs/build/<n>/`
+# (the local per-version build output) before deploydocs — wrong: that
+# directory becomes the *nested* `dev/` (etc.) subfolder on gh-pages, not
+# its root, and `.nojekyll` only has any effect at the true branch root.
+# deploydocs' own git push (see DocumenterVitepress/src/writer.jl) checks
+# out the *existing* gh-pages branch and only touches specific known
+# paths (each version's own subfolder, versions.js, the root redirect
+# index.html) rather than wiping the branch — so a root `.nojekyll`
+# added once, directly, persists across every future automated deploy.
+# Added that way instead (see the Investigation Log for the real
+# gh-pages-was-never-enabled story this was found alongside), not
+# reproduced here as build-time logic since there's nothing in the local
+# build tree that actually corresponds to the branch's real root.
 
 DocumenterVitepress.deploydocs(;
     repo="github.com/Richard7987/AsteroidPipeline.jl",
blob - e01a25c74205d65cfec9fce040385e20a8626e17
blob + ace5a2f778c8bbfcfa7c8a9581993aaf8e4a51f7
--- docs/src/design-refinements.md
+++ docs/src/design-refinements.md
@@ -50,3 +50,41 @@ missing was visibility: added a `@warn` (once per sess
 `maxlog=1`, so it doesn't spam a caller who's already made an informed
 choice) when both are left `nothing`. Regression test confirms it fires
 when omitted and stays silent when both are supplied.
+
+## GitHub Pages was never actually serving the wiki, despite a working deploy pipeline
+
+The GitHub mirror's docs site returned 404 even though
+`.github/workflows/Documenter.yml` reported `success` on every run, and
+`deploydocs` printed a clean `Deploying: ✔` with all five criteria
+checked. Diagnosed with `gh` (installed and authenticated specifically
+for this, not guessed from log snippets) rather than assumed from the
+green checkmark: `gh api repos/.../pages` returned a plain 404
+("Not Found") — GitHub Pages itself was disabled at the repository
+level, Source stuck on "None". The workflow's own job log, read in
+full, confirmed the deploy step really had pushed a working site:
+`fatal: 'upstream/gh-pages' is not a commit` (the expected first-deploy
+message), followed by a clean orphan-branch creation and a real push —
+git's own "Create a pull request for 'gh-pages'" hint, which only
+appears when a *new* branch is actually accepted by the remote. So the
+branch existed with real content; nothing was being served from it
+because Pages was off, a setting independent of whether gh-pages exists.
+Fixed directly: `gh api repos/.../pages -X POST` with
+`source.branch=gh-pages`, confirmed via the API's own `status: "built"`
+and a live `curl` returning 200 on multiple pages.
+
+A related, real mistake made and caught in the same investigation: a
+first attempt at adding a `.nojekyll` file (see above) touched it into
+`docs/build/<n>/` before `deploydocs` ran, reasoning that this local
+directory was "the site root." It isn't — `deploydocs` copies that
+directory's contents into a nested `dev/` subfolder of the actual
+gh-pages branch, generating `versions.js` and a redirect `index.html`
+separately at the *real* root, which no local directory corresponds to.
+Confirmed by listing the live branch's root contents via `gh api`
+(`dev/`, `index.html`, `versions.js` — no `.nojekyll` anywhere) after
+the first attempt had already been deployed. Corrected by adding
+`.nojekyll` directly to the gh-pages root via the API instead, a
+one-time fix rather than build-time logic: `deploydocs`'s own push
+mechanism checks out the *existing* branch and only touches specific
+known paths (each version's subfolder, `versions.js`, the root
+`index.html`) rather than wiping it, so a root file added once persists
+across every future automated deploy.