commit a91743def7ed40e47ad2d68dc75a967b2b2e9a7c from: ale date: Tue Aug 18 01:33:59 2026 UTC Correct the .nojekyll fix: it needs to be at gh-pages' real root, not inside the per-version build dir The previous commit touched .nojekyll into docs/build//, reasoning that directory was "the site root" — it isn't; deploydocs copies it into a nested dev/ subfolder of the actual gh-pages branch, with versions.js/index.html generated separately at the true root, which no local directory corresponds to. Confirmed by listing the live branch's root via the GitHub API after the wrong version had already deployed: dev/, index.html, versions.js — no .nojekyll anywhere. Fixed by adding .nojekyll directly to gh-pages' root via the API instead (already done, this commit just documents it and removes the ineffective build-time code) — a one-time fix, not build-time logic, since deploydocs' own push only touches specific known paths on each run rather than wiping the branch, so a root file added once persists. Also documents the actual root cause of the GitHub Pages outage this was found alongside: Pages was never enabled at the repository level (Source stuck on "None"), independent of gh-pages existing with a real, working build — the green "success" on every workflow run was correctly reporting the deploy step's own success, not whether Pages was serving anything. 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//`, 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//` +# (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//` 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.