Upgrade to Docusaurus 3#3144
Open
karlcarstensen wants to merge 20 commits into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Too much diff to scan? Review this PR in Change Stack to start with the highest-impact changes. Warning Review limit reached
More reviews will be available in 42 minutes and 18 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (5)
WalkthroughThis PR modernizes the documentation site and component architecture by upgrading to Docusaurus v4 features, standardizing documentation markup syntax across installation guides, refactoring code block components to use shared theming and context, and updating build configuration with dependency upgrades and infrastructure improvements. ChangesDocumentation markup and content updates
Code block component refactoring
Build configuration and infrastructure updates
🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
oredavids
reviewed
May 19, 2026
| > `docs-sourcer`'s `src/services/content-service.ts` to `{/* ##DOCS-SOURCER-START` | ||
| > and `##DOCS-SOURCER-END */}`, release a new version, then this repo's existing | ||
| > file format works directly. After that, the `<!-- -->` wrappers can be removed | ||
| > from these files. |
Contributor
There was a problem hiding this comment.
The docs-sourcer has two usage mechanisms:
- on demand: to run plugins when desired
- webhook-integration: the docs-sourcer is deployed as an app and responds to GitHub events to open PRs automatically for preview usecases and module releases in the IAC library repos
The integration means we can't rely on
do not run
yarn run-docs-sourcer(oryarn regenerate)
since we would likely break docs on the next automated release.
The docs-sourcer needs to be updated first to align with the v3 required changes and then used to regenerate all its content so we can merge that in as prep for the v3 migration. That would
- Make this PR significantly easier to review.
- Ensure the metadata signature is updated by the tool that generated the automated content.
- Prevent breaking the webhook-integration
The next steps as I see them are:
- Itemizing all the changes that need to happen in the docs-sourcer. I already noted the metadata comment wrapping, link updates, Github discussion body updates(they contain html comments)
- Dropping all changes to files that have the docs-sourcer metadata from this PR
- Implementing the changes in docs-sourcer
- Doing a re-run with the new docs-sourcer to correctly update content it manages
- Coordinating the merge of those changes with the actual v3 change.
Collaborator
Author
There was a problem hiding this comment.
This is really helpful context. All 1058 sourcer-managed files reset to main's content.
docs-sourcer could implement the v3-compat changes:
- Wrap blocks in {/* … */}
- Same for /END_… markers
Until docs-sourcer ships these updates, any automated PR it opens against this branch will use HTML comments and break the v3 build
oredavids
requested changes
May 19, 2026
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx (1)
456-459:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFix the broken
--template-urlquoting in the Azure boilerplate example.Line 458 is missing the closing
'around the template URL, so the command won’t run when copied.Suggested fix
- --template-url 'github.com/gruntwork-io/terragrunt-scale-catalog//templates/boilerplate/azure/gitlab/infrastructure-live?ref=v1.11.0 \ + --template-url 'github.com/gruntwork-io/terragrunt-scale-catalog//templates/boilerplate/azure/gitlab/infrastructure-live?ref=v1.11.0' \🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx` around lines 456 - 459, The `--template-url` argument in the Azure boilerplate example is missing the closing quote; update the example so the `--template-url` value is enclosed in matching single quotes (i.e., add the missing trailing '\'' after v1.11.0) so the shell command using the `boilerplate` CLI with `--template-url 'github.com/...?ref=v1.11.0'` runs correctly.docs/2.0/docs/pipelines/installation/addingnewrepo.mdx (1)
536-562:⚠️ Potential issue | 🟠 Major | ⚡ Quick winUse distinct, correct checklist IDs for Azure plan vs apply steps.
Line 539/540 currently labels the plan section as “Run an apply,” and it reuses
id="run-apply"again at Line 560. This makes the checklist ambiguous and can cause linked checkbox state.Suggested fix
-<PersistentCheckbox - id="run-apply" - label="Run an apply in the subscription directory to provision the resources in your Azure subscription." -/> +<PersistentCheckbox + id="run-plan" + label="Run a plan in the subscription directory to make sure that everything is set up correctly." +/> ... <PersistentCheckbox id="run-apply" label="Run an apply in the subscription directory to provision the resources in your Azure subscription." />🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/2.0/docs/pipelines/installation/addingnewrepo.mdx` around lines 536 - 562, The two PersistentCheckbox components reuse id="run-apply" and mislabel the plan step; change the first checkbox (the plan section at the earlier block) to a distinct id like id="run-plan" and update its label to "Run a plan in the subscription directory to preview changes." Leave the later checkbox for apply as id="run-apply" with its existing label, ensuring unique ids (e.g., run-plan vs run-apply) so checkbox state and labels are unambiguous.docusaurus.config.js (1)
158-208:⚠️ Potential issue | 🟠 Major | ⚡ Quick winDuplicate
sitemapkeys disable the custom lastmod workaround.The preset options define
sitemaptwice. The second block (Line 197 onward) overwrites the first, socreateSitemapItems(Lines 169–187) never runs and the source-file-path normalization is effectively dead code.Suggested fix
- sitemap: { - lastmod: "date", - changefreq: null, - priority: null, - // Workaround for Docusaurus 3.10: the sitemap plugin queries - // future.experimental_vcs.getFileLastUpdateInfo() with a relative - // sourceFilePath (e.g. "docs/foo.md"), but vcsGitEager indexes by - // absolute path, so every <lastmod> resolves to null. Resolve each - // route's sourceFilePath against the site root before letting the - // default builder run. - // TODO: remove once Docusaurus fixes the path-format mismatch. - createSitemapItems: async ({ - routes, - siteConfig, - defaultCreateSitemapItems, - }) => { - const path = require("path") - const fixRoute = (route) => { - const rel = route.metadata && route.metadata.sourceFilePath - if (rel && !path.isAbsolute(rel)) { - route.metadata = { - ...route.metadata, - sourceFilePath: path.resolve(__dirname, rel), - } - } - if (route.routes) route.routes.forEach(fixRoute) - } - routes.forEach(fixRoute) - return defaultCreateSitemapItems({routes, siteConfig}) - }, - }, + sitemap: { + lastmod: "date", + changefreq: null, + priority: null, + filename: "sitemap.xml", + ignorePatterns: [ + "/tags/**", + "/search", + "/home", + "/test-customizable-value", + ], + // Workaround for Docusaurus 3.10: the sitemap plugin queries + // future.experimental_vcs.getFileLastUpdateInfo() with a relative + // sourceFilePath (e.g. "docs/foo.md"), but vcsGitEager indexes by + // absolute path, so every <lastmod> resolves to null. Resolve each + // route's sourceFilePath against the site root before letting the + // default builder run. + // TODO: remove once Docusaurus fixes the path-format mismatch. + createSitemapItems: async ({ + routes, + siteConfig, + defaultCreateSitemapItems, + }) => { + const path = require("path") + const fixRoute = (route) => { + const rel = route.metadata && route.metadata.sourceFilePath + if (rel && !path.isAbsolute(rel)) { + route.metadata = { + ...route.metadata, + sourceFilePath: path.resolve(__dirname, rel), + } + } + if (route.routes) route.routes.forEach(fixRoute) + } + routes.forEach(fixRoute) + return defaultCreateSitemapItems({routes, siteConfig}) + }, + }, ... - sitemap: { - lastmod: "date", - changefreq: null, - priority: null, - filename: "sitemap.xml", - ignorePatterns: [ - "/tags/**", - "/search", - "/home", - "/test-customizable-value", - ], - },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docusaurus.config.js` around lines 158 - 208, There are two sitemap entries so the second one overwrites the first and your createSitemapItems logic never runs; merge them by keeping the sitemap object that contains createSitemapItems and adding the filename and ignorePatterns from the later sitemap block into that same sitemap object (retain lastmod/changefreq/priority as currently set), i.e., locate the sitemap object that defines createSitemapItems (references: createSitemapItems, routes, defaultCreateSitemapItems) and add filename: "sitemap.xml" and the ignorePatterns array into that object, then remove the duplicate sitemap block.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@jest.config.js`:
- Line 12: The testPathIgnorePatterns array uses regex strings and currently
contains "/.claude/" and "/.docusaurus/" which treat '.' as "any character" and
over-match; update the entries in the testPathIgnorePatterns configuration so
the dots are escaped (e.g., change "/.claude/" → "/\\.claude/" and
"/.docusaurus/" → "/\\.docusaurus/") while leaving "/node_modules/" and
"/build/" unchanged, ensuring the patterns correctly match hidden directories
only.
In `@package.json`:
- Line 64: package.json currently lists "typescript": "^6.0.0" which is
incompatible with ts-jest@27.1.3 (peer <5); update package.json's "typescript"
entry to a v4.x pin (for example "^4.9.5" or "<5") for this PR, run your package
manager to update lockfile (npm/yarn/pnpm) and re-run tests; alternatively, if
you prefer upgrading tooling, bump ts-jest/jest to versions that explicitly
support TypeScript 6 instead of changing "typescript" in package.json.
---
Outside diff comments:
In `@docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx`:
- Around line 456-459: The `--template-url` argument in the Azure boilerplate
example is missing the closing quote; update the example so the `--template-url`
value is enclosed in matching single quotes (i.e., add the missing trailing '\''
after v1.11.0) so the shell command using the `boilerplate` CLI with
`--template-url 'github.com/...?ref=v1.11.0'` runs correctly.
In `@docs/2.0/docs/pipelines/installation/addingnewrepo.mdx`:
- Around line 536-562: The two PersistentCheckbox components reuse
id="run-apply" and mislabel the plan step; change the first checkbox (the plan
section at the earlier block) to a distinct id like id="run-plan" and update its
label to "Run a plan in the subscription directory to preview changes." Leave
the later checkbox for apply as id="run-apply" with its existing label, ensuring
unique ids (e.g., run-plan vs run-apply) so checkbox state and labels are
unambiguous.
In `@docusaurus.config.js`:
- Around line 158-208: There are two sitemap entries so the second one
overwrites the first and your createSitemapItems logic never runs; merge them by
keeping the sitemap object that contains createSitemapItems and adding the
filename and ignorePatterns from the later sitemap block into that same sitemap
object (retain lastmod/changefreq/priority as currently set), i.e., locate the
sitemap object that defines createSitemapItems (references: createSitemapItems,
routes, defaultCreateSitemapItems) and add filename: "sitemap.xml" and the
ignorePatterns array into that object, then remove the duplicate sitemap block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: a63f0ef1-1650-460e-b33f-01d05b765552
⛔ Files ignored due to path filters (1)
yarn.lockis excluded by!**/yarn.lock,!**/*.lock
📒 Files selected for processing (34)
.gitignoredocs/2.0/docs/library/guides/integrate-tfc.mddocs/2.0/docs/library/tutorials/deploying-your-first-gruntwork-module.mddocs/2.0/docs/overview/concepts/gruntworkplatform.mddocs/2.0/docs/patcher/guides/promotion-workflows.mddocs/2.0/docs/patcher/tutorials/applying-first-patch.mddocs/2.0/docs/patcher/tutorials/authoring-first-patch.mddocs/2.0/docs/pipelines/guides/extending-pipelines.mddocs/2.0/docs/pipelines/installation/addingexistinggitlabrepo.mdxdocs/2.0/docs/pipelines/installation/addingexistingrepo.mdxdocs/2.0/docs/pipelines/installation/addinggitlabrepo.mdxdocs/2.0/docs/pipelines/installation/addingnewrepo.mdxdocs/2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4.mddocs/2.0/docs/pipelines/previous-versions/upgrading-gitlab-v1-to-v2.mddocs/2.0/docs/pipelines/tutorials/deploying-your-first-infrastructure-change.mdxdocs/2.0/docs/pipelines/tutorials/destroying-infrastructure.mdxdocs/2.0/way/why/velocity.mddocs/library/stay-up-to-date/updating.mddocs/library/stay-up-to-date/versioning.mddocusaurus.config.jsjest.config.jspackage.jsonscripts/vercelbuild.shsrc/clientModules/segmentShim.jssrc/components/CustomizableValue.tsxsrc/theme/CodeBlock/Content/Element.tsxsrc/theme/CodeBlock/Content/String.tsxsrc/theme/CodeBlock/Content/styles.module.csssrc/theme/CodeBlock/CopyButton/index.tsxsrc/theme/CodeBlock/CopyButton/styles.module.csssrc/theme/CodeBlock/Line/index.tsxsrc/theme/CodeBlock/Title/index.tsxtests/scripts/sidebar-lib.spec.tstsconfig.json
💤 Files with no reviewable changes (6)
- src/theme/CodeBlock/Content/String.tsx
- docs/library/stay-up-to-date/updating.md
- docs/library/stay-up-to-date/versioning.md
- src/theme/CodeBlock/Content/Element.tsx
- src/components/CustomizableValue.tsx
- src/theme/CodeBlock/Content/styles.module.css
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
2 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.
Summary
Brings the docs site green on Docusaurus 3 with future.v4: true and trailingSlash: true. Five categories of mechanical changes plus targeted swizzle rewrites for the CodeBlock theme refactor.
What changed
1. MDX 3 syntax compliance (~595 doc files)
2. CodeBlock theme swizzle migration (src/theme/CodeBlock/)
Docusaurus 3 rewrote the CodeBlock components around a new context provider + slot-based architecture. The site's three customizations (CustomizableValue integration in titles, copy handler, and line tokens) were ported.
3. Redirect collisions (2 deletions)
Removed docs/library/stay-up-to-date/{updating,versioning}.md. These pages had been superseded by /2.0/docs/library/guides/updating-modules and /versioning, with redirects already in src/redirects.js. The new client-redirects plugin refuses to overwrite real pages (older versions silently ignored this).
4. Internal link rewrites (~131 doc files)
Replaced 148 internal references to the deleted pages with their /2.0/docs/library/guides/... equivalents. Docusaurus 3's broken-link checker no longer trusts redirect targets, so links must point to canonical URLs.
5. Trailing-slash relative-path fixes (14 files)
The trailingSlash: true change broke a small number of pre-existing relative links (now resolving one directory deeper than intended). Converted to absolute paths or corrected ../ depth in:
6. Segment plugin runtime guard
Added src/clientModules/segmentShim.js, registered in docusaurus.config.js. The unmaintained @twilio-labs/docusaurus-plugin-segment@0.1.0 (peer-deps React 16/17) loads its onRouteDidUpdate callback in Docusaurus 3 dev mode despite skipping the inline init snippet, leaving window.analytics undefined and crashing on navigation. The shim defines window.analytics as a no-op fallback, which also hardens production against ad-blockers/CSP that block the Segment loader.
Test plan
Out of scope
Summary by CodeRabbit
New Features
Documentation
Refactoring
Chores