Skip to content

Commit 5eb180e

Browse files
ci(docs): set include-hidden-files=true to preserve .nojekyll for Pages
QA-driven follow-up to b1ce91c (the bulk Node-20 sweep). The QA reviewer flagged that Pages action release notes weren't cited in the same detail as actions/* bumps; pulling them now revealed: upload-pages-artifact v4.0.0 release notes: > "Potentially breaking change: hidden files (specifically > dotfiles) will not be included in the artifact" MkDocs Material's `mkdocs build` writes `.nojekyll` to `site/` so GitHub Pages skips Jekyll processing on the published artifact — without `.nojekyll`, any path beginning with `_` (which MkDocs Material uses for `_static/`, `_sources/`, etc.) gets 404'd by GitHub Pages's Jekyll filter, breaking large parts of the site. The new `include-hidden-files: true` input added in upload-pages-artifact v5.0.0 (per its release notes) restores the v3 behavior of including dotfiles. Setting it explicitly makes the contract intent visible in the workflow. Why this is "safe today, broken when public": - docs.yml deploy job is guarded by `if: ... repository.private == false`. Repo is currently private (Phase 3.4 hasn't flipped yet), so Pages deploy is a no-op today. - When Phase 3.4 flips public, this step starts firing — and WITHOUT `include-hidden-files: true`, the deploy would silently exclude `.nojekyll` and the published site would have broken asset paths. - Catching this BEFORE the flip is cheap. Catching it AFTER would show up as customer-facing 404s on docs. No DECISION_LOG entry — this is a defensive parameter add on top of the bulk sweep, not a new architectural decision. The MEDIUM- severity QA finding from the b1ce91c review is closed by this commit. doc-drift OK. YAML parses clean.
1 parent b1ce91c commit 5eb180e

1 file changed

Lines changed: 9 additions & 0 deletions

File tree

.github/workflows/docs.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,15 @@ jobs:
149149
uses: actions/upload-pages-artifact@v5
150150
with:
151151
path: site/
152+
# upload-pages-artifact v4.0.0 introduced a "hidden files are
153+
# excluded by default" change. MkDocs Material writes
154+
# `.nojekyll` to `site/` so GitHub Pages skips Jekyll
155+
# processing — without that file, GitHub Pages would 404 on
156+
# mkdocs-emitted paths starting with `_` (assets/_static
157+
# paths, etc.). Setting include-hidden-files: true preserves
158+
# v3 behavior and ensures the deploy is correct when Phase
159+
# 3.4 flips the repo public and this step actually fires.
160+
include-hidden-files: true
152161

153162
- name: Deploy to GitHub Pages
154163
id: deployment

0 commit comments

Comments
 (0)