Skip to content

docs: add redirects.json and rebuild the docs site when it changes - #30208

Merged
nickvigilante merged 1 commit into
mainfrom
vigilante/docs-1156-codercoder-add-docsredirectsjson-and-rebuild-codercom-when
Oct 2, 2026
Merged

nickvigilante merged 1 commit into
mainfrom
vigilante/docs-1156-codercoder-add-docsredirectsjson-and-rebuild-codercom-when

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Adds docs/redirects.json (an empty list for now) so a docs page move and its redirect can land in one PR, and makes the docs site rebuild when that file changes.

The vercel-rebuild job in deploy-docs.yaml only fired when docs/manifest.json changed, so a redirects-only push would have waited for the daily rebuild. The changes job now also emits redirects_changed, and the rebuild runs when either output is true. manifest_changed is deliberately untouched: it also forces the whole-branch search reindex, which a redirect change does not need. On a first push to a branch or when the diff cannot be computed, redirects_changed is true, like manifest_changed. For non-push events it is false. The rebuild step summary now names whichever file changed, and is byte-identical to before for manifest-only pushes.

The docs contributing guidance (content-guidelines.md, DOCS_STYLE_GUIDE.md, and the doc-check and write-docs skills) told authors to open a second PR in the website repository for a redirect. It now points at docs/redirects.json, documents the rule shape, and says to backport a move together with its redirect, since the unversioned docs are served from the mainline release branch.

This is a draft because the file has no effect until the website build reads it. Redirects that predate this file are unchanged. The audit-docs-paths workflow still reads only the existing website redirect file and is not touched here. Once merged, the cherry-pick label would bring the initial file to the mainline release branch.

Verification (run locally; the workflow itself has not run in GitHub Actions, and the if: expression is only evaluated by GitHub):

I extracted the real changes step script from the old and new workflow files and ran each against a throwaway local git remote, one commit per scenario, with gawk on PATH:

Push changes before: manifest_changed after: manifest_changed, redirects_changed
redirects only false false, true
manifest only true true, false
markdown only false false, false
image only false false, false
manifest and redirects true true, true
workflow_dispatch false false, false
new branch (zero SHA) true true, true
unfetchable BEFORE_SHA true true, true

manifest_changed and paths_json are identical to before in every scenario.

I also ran the real vercel-rebuild step against a local fake deploy hook. The Reason line reads `docs/manifest.json` changed for a manifest-only push (summary file byte-identical to the old workflow's), `docs/redirects.json` changed for a redirects-only push, and names both when both changed.

Checks run, all exit 0: actionlint (clean on the old file too), zizmor --strict-collection --persona=regular, make lint/emdash, go run ./scripts/docshtmlcheck, go run ./scripts/styleclaims, and the repo-pinned markdownlint-cli2 v0.16.0 over the 514 files pnpm lint-docs covers (no --fix).

Not run: Vale (mise does not trust mise.toml in a fresh worktree), typos (not installed), and the repository git hooks (opt-in, not enabled).


🤖 Built with AI assistance.

CI notes
  • gen, offlinedocs, and required failed on docs/manifest/generated/cli.json drift that came from main (fixed there in fix(docs): regenerate CLI manifest for coder sharing #30216), not from this PR. Rebased onto main to pick up the fix; the merge commit from the previous update is gone.
  • Storybook then failed because the Pixel upload returned HTTP 500 for 11 snapshots and the browser context closed mid-run. This PR changes no frontend code, so it is a flake. Failed job rerun.

Generated by Coder Agents on behalf of @nickvigilante.

@linear-code

linear-code Bot commented Sep 30, 2026

Copy link
Copy Markdown

DOCS-1156

Add docs/redirects.json, an empty list of redirect rules, so a docs page
move and its redirect can ship in the same PR. The docs website reads
the file at build time.

The deploy-docs workflow already rebuilds the website when
docs/manifest.json changes. Give docs/redirects.json its own
redirects_changed signal and rebuild on either file. It is a separate
output so a redirects-only push does not also force the whole-branch
search reindex that a manifest change does. The rebuild step summary now
names the file that changed.

Update the docs contributing guidance that told authors to open a second
PR in the website repository for a redirect.

Assisted-by: AI
@nickvigilante
nickvigilante force-pushed the vigilante/docs-1156-codercoder-add-docsredirectsjson-and-rebuild-codercom-when branch from 48c3b42 to 127919c Compare October 1, 2026 15:42
@nickvigilante
nickvigilante marked this pull request as ready for review October 1, 2026 21:03

@Jesswinters Jesswinters left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! :-}

@nickvigilante
nickvigilante merged commit 14bb1f2 into main Oct 2, 2026
82 of 86 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-1156-codercoder-add-docsredirectsjson-and-rebuild-codercom-when branch October 2, 2026 14:30
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 2, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants