D8 canonical refresh: inline root-redirect HTML, drop template file (adopts D20-Dice pattern) - #408
Merged
Merged
Conversation
Adopts the D20-Dice pattern (proven on Chris-Wolfgang/D20-Dice
commit b58861a) as the canonical pattern for the gh-pages root
landing.
Two changes:
1. .github/workflows/docfx.yaml — the 'Generate version-picker
index.html' step no longer reads and substitutes a template
file. It now builds the HTML inline as a PowerShell string
array (joined with LF) directly in the workflow. Only the
page title ($repoName) is interpolated; the former
{{VERSION_LIST}} expansion is gone because the in-page
version picker (public/version-picker.js) handles version
switching from any docs page, so the root no longer needs a
clickable list. String-array form (rather than a here-string)
avoids the YAML literal-block-scalar indentation trap where
unindented inner here-string lines would prematurely terminate
the outer block.
2. .github/version-picker-template.html — DELETED. With docfx.yaml
no longer reading it, no workflow step references the file.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the DocFX GitHub Pages deployment workflow to generate the gh-pages root landing page (index.html) inline (a redirect to versions/latest/) and removes the now-unused .github/version-picker-template.html file, aligning with the newer “D20-Dice” pattern described in the PR.
Changes:
- Inline-generate the root redirect
index.htmlin.github/workflows/docfx.yaml(no template file / no version-list substitution). - Remove the
.github/version-picker-template.htmlfile from the repo.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
.github/workflows/docfx.yaml |
Replaces template-based root page generation with inline PowerShell HTML string construction for a redirect landing page. |
.github/version-picker-template.html |
Deleted the template file previously used to generate the root landing page. |
Two findings from copilot-pull-request-reviewer:
1. (line 555 of docfx.yaml) — the comment said the redirect targets
'/versions/latest/' (absolute) but the generated HTML correctly
uses a relative 'versions/latest/' link (required for GitHub Pages
project sites under '/<repo>/'). Reworded the comment to call out
the relative link explicitly so a future maintainer doesn't
'helpfully' change it to absolute.
2. (line 565 of docfx.yaml — actually broader) — deleting
.github/version-picker-template.html breaks two other references:
a. .github/workflows/build-all-versions.yaml has its own 'Generate
root index.html' step that reads the template and substitutes
{{TITLE}} + {{VERSION_LIST}}. Refactored that step the same way:
inline string-array HTML, only the title is dynamic, step
renamed to 'Generate root index.html (meta-refresh → versions/
latest/)'. Now both workflows produce identical markup.
b. docs/DOCFX-VERSION-PICKER.md documented the template-based flow
in three places. Updated all three: section '### 4.' now
explains the inline-HTML approach (with a note about why the
template file was removed); the gh-pages flow diagram refers to
'Generate root index.html (meta-refresh, inline HTML)'; the
troubleshooting table's 'old landing page' row points at the
new step name.
Step-name accuracy in docs/DOCFX-VERSION-PICKER.md: - The doc previously implied docfx.yaml has a distinct 'Generate root index.html (meta-refresh)' step. It doesn't — the inline HTML generation runs inside the 'Deploy docs to GitHub Pages' step as inline PowerShell, surfacing only as a Write-Host log line. - build-all-versions.yaml DOES have a distinct step at the workflow's top level, named 'Generate root index.html (meta-refresh → versions/latest/)'. Updated the section-4 note + the troubleshooting table row so readers know where to look in each workflow when debugging the 'old landing page' symptom.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adopts the D20-Dice pattern (commit
b58861a) as the new canonical for the gh-pages root landing.What changes
.github/workflows/docfx.yamlThe "Generate version-picker index.html" step no longer reads and substitutes a template file. It now builds the HTML inline as a PowerShell string array (joined with
LF) directly in the workflow:setTimeoutbackup +<noscript>link — three layers of redirect fallback$repoName) is interpolated; the former{{VERSION_LIST}}expansion is gone because the in-page version picker (public/version-picker.js) handles version-switching from any docs page, so the root no longer needs a clickable list.github/version-picker-template.html— DELETEDWith
docfx.yamlno longer reading it, no workflow step references the file. Keeping it would invite confusion.Fleet-wide propagation
27 downstream repos still carry the file and reference it from their
docfx.yaml. After this lands, the same change fans out viabulk-repo-pr. Each downstream PR will need admin-bypass merge because both modifications touch protected paths (.github/workflows/docfx.yamland the file under.github/).Why this is better than the previous canonical
The previous canonical pattern had the workflow read a separate HTML file, regex-substitute
{{TITLE}}and{{VERSION_LIST}}, write the result. The{{VERSION_LIST}}substitution was already a no-op after D8's in-page picker shipped (DateTime PRs #200 /bab3a5f), so the template file was just dead weight that pretended to be parameterized.The D20-Dice pattern is leaner (no template file, no regex substitution), more honest (the workflow shows you exactly what HTML it produces), and removes a file from every repo (-27 files fleet-wide).