Fix internal links to old /docs/concepts/ URLs (redirect-hop cleanup) - #21072
Merged
workprentice[bot] merged 4 commits intoAug 25, 2026
Merged
Conversation
Several docs, blog, and tutorial pages still link to the pre-restructure /docs/concepts/... URLs, which now 301 (some via a double hop) to their current /docs/iac/concepts/..., /docs/esc/concepts/, or /docs/reference/glossary/ locations. Updated 79 files (154 link occurrences, both root-relative markdown links and fully-qualified https://www.pulumi.com/... links) to point directly at the final destination, verified live against the current redirect map. Every fragment (#anchor) and the handful of double-hop cases (missing trailing slash -> slash -> new path) were preserved/collapsed correctly. One additional file with the same pattern (content/blog/why-choose-pulumi-over-terraform/index.md) was intentionally left untouched because it already has open PRs (#21062, #21066) touching it today; filed a follow-up board card to catch it separately.
github-actions
Bot
added
the
review:triaging
Contributor
Author
|
@claude #new-review |
github-actions
Bot
added
domain:docs
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Optional style suggestions from the pre-merge review — apply or dismiss; none of them block.
Generated by Claude Code
Contributor
Pre-merge Review — Last updated 2026-08-24T22:18:40ZTip Summary: Review confidence:
Investigation log
✏️ 3 one-click style suggestions are posted inline — apply them from the Files changed tab, individually or with Add suggestion to batch. 🔍 Verification trail158 claims extracted · 118 verified · 16 unverifiable · 10 contradicted · 2 framing-drift · 6 detector findings
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
Contributor
continued from previous comment
📊 Editorial balanceSingle-subject post; balance check N/A. 🚨 Outstanding in this PRNone, and none introduced by
|
Contributor
📋 Triaged verifier findingsI double-checked these and realized they weren't real findings — click to expand
💡 Pre-existing issues in touched files (optional)
✅ Resolved since last review
📜 Review history
Important Please don't hide, resolve, or delete this comment! It breaks things! 📖 How pre-merge review works — the full lifecycle, short-circuits, and escape hatches. |
Collaborator
github-actions
Bot
added
review:outstanding-issues
Contributor
|
@workprentice Work through the findings in the review, please :) |
Follow-up to the automated review of the /docs/concepts/ redirect-hop cleanup. The path rewrites were correct, but several rewritten links kept a #fragment whose section had moved off the destination page entirely, adding back a second (client-side JS) redirect hop -- exactly what this PR set out to remove: - #components -> /docs/iac/concepts/components/ - #autonaming -> /docs/iac/concepts/resources/names/#autonaming - #urns -> /docs/iac/concepts/resources/names/#urns - #dependson -> /docs/iac/concepts/resources/options/dependson/ - #explicit-provider-configuration -> /docs/iac/concepts/providers/ - #additionalsecretoutputs -> /docs/iac/concepts/resources/options/additionalsecretoutputs/ - #transformations -> /docs/iac/concepts/resources/options/transformations/ Applied across all lines in this PR's diff carrying these anchors (verified each target live), including a couple the review didn't individually cite but that matched the same pattern. Also fixed two mislabeled docs-page links flagged by review in content/docs/iac/guides/migration/import/_index.md: a `retainOnDelete` mention that pointed at the unrelated `protect` option's page (now points at its own retainOnDelete page), and a `#autonaming` anchor pointing at the wrong page (now the names page). Fixed three "Pulumi Service" (deprecated product name) mentions on lines this PR already touches, per STYLE-GUIDE.md: keep-your-secrets-secure-by-default, six-things-about-pulumi-service, and stack-readme now say Pulumi Cloud / Pulumi Cloud console, and the six-things and keep-your-secrets posts' own links to the old /product/pulumi-service/ and /docs/pulumi-cloud/self-hosted/ URLs (which themselves redirect) now point directly at their live targets. Verified: node ./scripts/lint/lint-markdown.js and yarn prettier --check on all 17 touched files, 0 errors; every new/changed anchor and link target fetched live to confirm a 200 response before use.
github-actions
Bot
added
review:stale
Contributor
Author
|
@CamSoper Thanks for the nudge — pushed a follow-up commit (420d3e8) that works through every finding in the pre-merge review: Stale anchors (9 flagged + several more matching the same pattern in this PR's diff) — all rewritten to their real destination instead of a
Also handled Two mislabeled docs-page links in Deprecated product name — fixed the three "Pulumi Service" mentions on lines this PR already touches ( Every new/changed target was fetched live to confirm a 200 before use. Could you (or another maintainer) comment |
github-actions
Bot
added
review:in-progress
Contributor
|
@claude #update-review For future reference @workprentice -- In this repo, please assume that a reviewer will want you to address all findings, including blockers and low-confidence findings. Also, you should plan on accepting all style suggestions unless they're just bad suggestions. Once you get the This has now been documented in Thanks! Here's a cookie as a token of my appreciation: 🍪 |
Contributor
There was a problem hiding this comment.
🧹 Optional style suggestions from the pre-merge review — apply or dismiss; none of them block.
Generated by Claude Code
Contributor
|
🤖 Review updated on @CamSoper's request. |
github-actions
Bot
removed
the
review:in-progress
github-actions
Bot
added
the
review:stale
Contributor
Author
|
Thanks — pushed Blocker (finished the Pulumi Cloud rename): the previous commit only renamed the one line in Style suggestions: applied 26 of the 27 flagged suggestions across 20 files — punctuation, wordiness, filler, weasel words, difficulty qualifiers, spacing, vague link text, an unbacked Declined one: "double click" → "double select" in
@claude #update-review |
github-actions
Bot
added
review:in-progress
Contributor
There was a problem hiding this comment.
🧹 Optional style suggestions from the pre-merge review — apply or dismiss; none of them block.
Generated by Claude Code
Contributor
|
🤖 Review updated on @workprentice[bot]'s request. |
github-actions
Bot
added
review:no-blockers
The 483d4d1 style sweep dropped meaning or grammar in five spots while clearing linter flags on adjacent words: - keep-your-secrets-secure-by-default L34: restore the "often" hedge ("is enough" -> "is often all you need") so the claim isn't stronger than the original and isn't contradicted by the next sentence. - ai-slack-bot-...-pulumi-on-aws L284: same shape, milder -- restore "often" before "happens" for the same reason. - iac-best-practices-understanding-code-organization-stacks L82: restore the coordinating clause the linter's target word was carrying ("lightweight to create or delete" -> "lightweight, and creating or deleting one is quick"). - next-level-iac-pulumi-runtime-logic L293, L331: restore "immediately" before "before the program exits" -- the removed "just" was temporal, not a difficulty qualifier, and matches the Node.js/Python docs this section quotes. - six-things-about-pulumi-service L48: fix a pre-existing "such the current git SHA" typo (missing "as") while already touching this line for the Pulumi Cloud rename. Verified: yarn prettier --check and node ./scripts/lint/lint-markdown.js both pass clean on all 5 touched files.
github-actions
Bot
added
review:stale
Contributor
Author
|
Thanks for the review:no-blockers pass — glad the Pushed
The remaining low-confidence items (17 total, 12 unaddressed) are all the pre-existing "cited page returned only navigation chrome, can't verify the claim" link-content findings — explicitly out of scope for a link-target rewrite and already marked as not blocking. Leaving those as-is per the review's own framing.
@claude #update-review |
github-actions
Bot
added
review:in-progress
Contributor
There was a problem hiding this comment.
🧹 Optional style suggestions from the pre-merge review — apply or dismiss; none of them block.
Generated by Claude Code
| As a reader of this blog, you've probably heard of [Pulumi Cloud](/product/), the default state-management [backend](/docs/iac/concepts/state-and-backends/) of the Pulumi CLI. If that's the case, there's also a good chance you've heard of several of its key features, like helping you organize your [projects and stacks](/docs/iac/concepts/stacks/), collaborate with others with the help of [organizations](/docs/administration/organizations-teams/organizations/), or handle sensitive data securely with built-in support for [encrypted secrets](https://www.pulumi.com/docs/iac/concepts/secrets/). | ||
|
|
||
| What you might not know, though, is that we're adding new features to the Pulumi Service all the time, and that some of these features can be fairly easy to miss. So in this post, we'll highlight a handful of the features you might _not_ be aware of, and that we think make it even easier to manage your infrastructure with Pulumi. | ||
| What you might not know, though, is that we're adding new features to Pulumi Cloud all the time, and that some of these features can be fairly easy to miss. So in this post, we'll highlight a handful of the features you might _not_ be aware of, and that we think make it even easier to manage your infrastructure with Pulumi. |
Contributor
There was a problem hiding this comment.
[style] weasel word — clears fairly/easy/So and a double space
Suggested change
| What you might not know, though, is that we're adding new features to Pulumi Cloud all the time, and that some of these features can be fairly easy to miss. So in this post, we'll highlight a handful of the features you might _not_ be aware of, and that we think make it even easier to manage your infrastructure with Pulumi. | |
| What you might not know, though, is that we're adding new features to Pulumi Cloud all the time, and that some of these features can slip past you. In this post, we'll highlight a handful of the features you might _not_ be aware of, and that we think make it even easier to manage your infrastructure with Pulumi. |
|  | ||
|
|
||
| When Pulumi updates a stack, it will store some information about the local machine state, such the current git SHA if the stack resides in a `git` repository. It is with this data that the Pulumi Service links to relevant services where possible. | ||
| When Pulumi updates a stack, it will store some information about the local machine state, such as the current git SHA if the stack resides in a `git` repository. It is with this data that Pulumi Cloud links to relevant services where possible. |
Contributor
There was a problem hiding this comment.
[style] wordiness — unpacks the cleft into a direct sentence
Suggested change
| When Pulumi updates a stack, it will store some information about the local machine state, such as the current git SHA if the stack resides in a `git` repository. It is with this data that Pulumi Cloud links to relevant services where possible. | |
| When Pulumi updates a stack, it will store some information about the local machine state, such as the current git SHA if the stack resides in a `git` repository. Pulumi Cloud uses this data to link to relevant services where possible. |
| {{% /notes %}} | ||
|
|
||
| There are plenty of other features to check out in the [Pulumi Service](/product/pulumi-service/), and we have exciting improvements on the way! As always, feel free to stop by the [Pulumi Community Slack](https://slack.pulumi.com) to learn more, ask questions, or share anything cool you’re up to! | ||
| There are plenty of other features to check out in [Pulumi Cloud](/product/), and we have exciting improvements on the way! As always, feel free to stop by the [Pulumi Community Slack](https://slack.pulumi.com) to learn more, ask questions, or share anything cool you’re up to! |
Contributor
There was a problem hiding this comment.
[style] filler — leads with the subject instead of There are
Suggested change
| There are plenty of other features to check out in [Pulumi Cloud](/product/), and we have exciting improvements on the way! As always, feel free to stop by the [Pulumi Community Slack](https://slack.pulumi.com) to learn more, ask questions, or share anything cool you’re up to! | |
| [Pulumi Cloud](/product/) has plenty of other features to check out, and we have exciting improvements on the way! As always, feel free to stop by the [Pulumi Community Slack](https://slack.pulumi.com) to learn more, ask questions, or share anything cool you’re up to! |
Contributor
|
🤖 Review updated on @workprentice[bot]'s request. |
github-actions
Bot
added
review:no-blockers
Contributor
Author
|
All clear — thanks for the careful read-back on On the one open item you flagged as needing a deliberate call rather than an oversight: leaving the partial Requesting team review now that this is at review:no-blockers. |
joeduffy
approved these changes
Aug 25, 2026
workprentice
Bot
deleted the
seo/fix-docs-concepts-internal-links-20260822
branch
August 25, 2026 02:08
CamSoper
pushed a commit
that referenced
this pull request
Aug 26, 2026
* Fix internal links to old /docs/concepts/ URLs missed by #21072 PR #21072 rewrote 79 files of content/ links from old /docs/concepts/* to their current /docs/iac/concepts/*, /docs/esc/concepts/*, and /docs/reference/glossary/* destinations, but its sweep covered content/ markdown links only. Three files outside that scope still pointed at old dead-hop paths: - layouts/migrate/terraform.html: a template href, not a content link - assets/openapi/tag-intros/stacks.md: OpenAPI docs intro fragment - content/docs/iac/concepts/resources/_index.md: a client-side JS hash-redirect map (5 of its 22 entries still pointed at the old paths, doing the same job the map exists for but landing on another redirect hop instead of the final page) Each old path was verified against its live redirect chain before rewriting, confirming the new destination resolves 200 directly: - /docs/concepts/vs/terraform -> /docs/iac/comparisons/terraform/ - /docs/concepts/stack/ -> /docs/iac/concepts/stacks/ - /docs/concepts/resources/components -> /docs/iac/concepts/components/ - /docs/concepts/resources/names -> /docs/iac/concepts/resources/names/ - /docs/concepts/resources/get -> /docs/iac/concepts/functions/get-functions/ The #urns and #autonaming anchors were confirmed present on the new resources/names/ page. content/blog/why-choose-pulumi-over-terraform/index.md is intentionally left untouched here; it is still blocked by open PRs #21062 and #21066 and is tracked separately. node ./scripts/lint/lint-markdown.js and ./scripts/prettier.sh --check both pass on the changed files (the one markdown-lint finding on assets/openapi/tag-intros/stacks.md is a pre-existing missing-heading warning on master, unrelated to this change). --- 🧠 *This PR was created by [workprentice](https://github.com/workprentice).* * Complete redirect-hop cleanup: TS redirect maps, toc.ts, and remaining stale content links PR #21138 fixed 3 non-content/ surfaces (an asset, the resources hash-redirect map, and a layout template) but left several sibling defects of the same class: - theme/src/ts/redirects.ts: a client-side hash-redirect map for the old /docs/intro/concepts/programming-model/ page pointed all 34 entries at dead /docs/concepts/* hops. Rewrote every entry to its live /docs/iac/concepts/* (or /docs/iac/concepts/inputs-outputs/*, /docs/iac/concepts/providers/*, etc.) destination, verified 200 with no further hop. - theme/src/ts/toc.ts: the left-nav active-state map still keyed off the old /docs/concepts/ path. - content/docs/iac/concepts/resources/_index.md: the hash-redirect map added by #21138 itself was missing trailing slashes on 16 of its 28 targets, each of which 302-redirects to the slashed form -- the same dead-hop defect this whole cleanup exists to remove. Added trailing slashes throughout. - Six remaining content files (archetypes template, two blog posts, the insights search reference-link footnotes, and the k8s operator integration page) still linked to old /docs/concepts/* paths; rewrote to their current /docs/iac/concepts/* destinations. Every new destination verified live against https://www.pulumi.com with redirects disabled: all return 200 directly. A further stale link was found in static-prebuilt/ ESC SDK reference HTML, but those files are generated from pulumi/esc's own SDK docstrings at build time, so fixing them here would be overwritten on next regeneration -- tracked separately for a pulumi/esc-side fix. * Fold in the 3 review-flagged /docs/concepts/ survivors Fixes the outstanding finding from the pre-merge review: - content/docs/iac/guides/clouds/aws/eks.md:307 -- a two-line markdown link the earlier single-line grep missed; repoints to the canonical /docs/iac/concepts/resources/options/transforms/. - scripts/search/rank.js:80 -- the search-ranking boost for concepts pages checked the retired /docs/concepts/ prefix, so it silently fell through to the generic docs score (860) instead of 890. - theme/src/ts/redirects.ts -- "#outputs-and-strings" now lands on the section anchor (#using-string-interpolation) instead of the top of the page, matching the other 33 entries' precision and the stub page's own redirect_to target. content/blog/why-choose-pulumi-over-terraform/index.md's three absolute-URL survivors are intentionally left out of this PR: that file already has two open PRs against it (#21062, #21066) and is tracked separately. * Fix crawler-facing meta refresh to skip the /docs/concepts redirect hop The two retired-URL stub pages (programming-model.md and programming-model-previous.md) still pointed their meta refresh at /docs/concepts, which now resolves as a 302-then-301 chain before landing on /docs/iac/concepts/. Point the refresh straight at the final destination instead, matching the visible prose link directly beneath it. Re-swept current master for the same defect class: the other three instances found (assets/openapi/tag-intros/stacks.md and the theme/src/ts/redirects.ts anchor map) are already fixed by this PR's earlier commits. * Remove dead /docs/using-pulumi/ ranking branch from search rank.js Review flagged this as a sibling of the /docs/concepts/ prefix defect this PR fixes: content/docs/using-pulumi no longer exists, and every remaining /docs/using-pulumi/... occurrence under content/docs/ is an `aliases:` entry (a historical redirect source), not a page's own `url:`. No indexed page's href ever starts with /docs/using-pulumi/, so the branch never fired -- pages that used to live there now score 860 or 870 via fallthrough, same as any other docs page. The content that used to live under /docs/using-pulumi/ moved to three different trees (iac/, insights/policy/, administration/) with no single successor prefix, so there's no one replacement string to substitute -- removing the dead branch is the honest fix rather than repointing it. --------- Co-authored-by: workprentice <257153108+workprentice@users.noreply.github.com>
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
4 participants
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.
What
Fixes internal links that still point at the pre-restructure
/docs/concepts/...URL space. Those URLs now 301 redirect (some via a double hop through a trailing-slash normalization) to their current homes under/docs/iac/concepts/...,/docs/esc/concepts/, or/docs/reference/glossary/.Why
Internal links that force a redirect hop waste crawl budget, dilute link equity, and add avoidable latency for readers.
/docs/iac/concepts/is one of the highest-impression pages on the site per Search Console, so cleaning up the links that feed it (and its sibling pages) is a direct, low-risk technical-SEO win.Scope
[label](/docs/concepts/...)) and fully-qualified links (https://www.pulumi.com/docs/concepts/...).200destination before rewriting (not guessed), and anchors (#fragment) were preserved.content/blog/why-choose-pulumi-over-terraform/index.md, was deliberately left untouched because it already has open PRs (SEO: fix CTR + internal links for "agentic infrastructure" query #21062, fix(seo): correct unsourceable claims and stale enumerations across blog #21066) touching it; a follow-up board card will catch it once those land.Verification
node ./scripts/lint/lint-markdown.json all 79 changed files: 0 errors.yarn prettier --checkon all 79 changed files: all pass.200final destination before use in the replacement map (30 distinct paths resolved).git diff --numstatconfirms 1:1 line replacement in every file (no unintended changes).🧠 This PR was created by workprentice.