Upgrade to Docusaurus 3

.gitignore

@@ -16,6 +16,9 @@ pids
 *.seed
 *.pid.lock
 
+# AI tools
+.claude/
+
 # Directory for instrumented libs generated by jscoverage/JSCover
 lib-cov
 
@@ -82,4 +85,4 @@ build/
 *.iml
 
 # VS Code files
-.vscode
+.vscode

README.md

@@ -17,6 +17,85 @@ Docs Sourcer is generally run in CI or via webhooks and doesn't have to be run l
 to run it locally you will need access to various secrets.  These secrets live in 1password under a secure note called
 "docs sourcer .env file".
 
+> **TODO — docs-sourcer / MDX 3 compatibility (Docusaurus 3 migration):**
+> The `##DOCS-SOURCER-*` metadata blocks are wrapped in `{/* ... */}` so MDX 3
+> accepts them, with the literal `<!-- ... -->` HTML markers preserved inside
+> for the docs-sourcer validator's `indexOf` check. This is a temporary bridge.
+>
+> **Do not run `yarn run-docs-sourcer` (or `yarn regenerate`) until docs-sourcer
+> is updated** — its `writeMetadata` strips from `<!--` and re-appends a plain
+> HTML-comment block, leaving an orphaned `{/*` and `*/}` that breaks the MDX
+> build.
+>
+> Durable fix: change `METADATA_START_TOKEN` / `METADATA_END_TOKEN` in
+> `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.
+
+### Sitemap `lastmod` requires a deep git clone on Vercel
+
+`docusaurus.config.js` enables `future.faster.gitEagerVcs: true` and
+`sitemap.lastmod: "date"`, so each `<url>` in `build/sitemap.xml` carries a
+`<lastmod>` derived from `git log` at build time.
+
+Vercel clones with `--depth 1` by default, which leaves git unable to
+determine when most files were last modified — every date would collapse to
+the deploy commit. `scripts/vercelbuild.sh` therefore prepends
+`git fetch --unshallow --filter=blob:none || true` before `yarn install`. The
+`|| true` keeps already-deep clones from failing the build.
+
+If you later enable `showLastUpdateTime` / `showLastUpdateAuthor` in the docs
+plugin, no further action is needed — they read from the same git source.
+
+### TypeScript `baseUrl` is deprecated and will hard-error in TS 7
+
+`tsconfig.json` sets `ignoreDeprecations: "6.0"` to silence one warning:
+`baseUrl` is deprecated in TS 5+ and removed in TS 7. We can't drop it
+locally because:
+
+- `@docusaurus/tsconfig` (the base we extend) also sets `baseUrl: "."`, which
+  TypeScript resolves relative to the *extended* file's location
+  (`node_modules/@docusaurus/tsconfig/`), not ours.
+- Removing only the local `baseUrl` makes the inherited one apply, which
+  resolves `@site/*` paths into the vendored Docusaurus directory and breaks
+  any swizzle that imports from `@site/...` (verified — two of our CodeBlock
+  swizzles fail to resolve).
+
+Two viable fixes when TS 7 lands:
+
+1. **Upstream fix:** drop `baseUrl` from `@docusaurus/tsconfig` and rely on
+   TS 5+ behavior where `paths` resolve relative to the tsconfig file. Then
+   drop our local `baseUrl` too.
+2. **Stop extending `@docusaurus/tsconfig`:** inline its options minus
+   `baseUrl`. Trades dependency on an upstream fix for a small amount of
+   config duplication.
+
+The pre-existing `npx tsc` errors (35 as of this writing) are unrelated and
+not enforced in CI; only `yarn build` and `yarn test` gate merges.
+
+### `onBrokenAnchors` is set to Docusaurus's default of `'warn'`
+
+The Docusaurus 3 migration tightened the broken-link checker to `'throw'`
+(default), which catches dead `<Link to>` targets and blocks builds. **Broken
+anchors** (e.g. `[text](/page/#missing-section)`) are still only warned about
+because ~22 pre-existing anchor breakages in `docs/reference/...` would
+otherwise block every build until they're fixed.
+
+Risk: a future PR can introduce a typo'd anchor and CI won't catch it.
+
+To escalate, in two steps:
+
+1. Fix the 22 existing broken anchors (`yarn build` lists them under
+   `[WARNING] Docusaurus static site generation process emitted warnings for
+   N paths`).
+2. Add `onBrokenAnchors: 'throw'` to `docusaurus.config.js`.
+
+The same applies — at lower priority — to the HTML-minifier nesting
+diagnostics that surface as warnings during build (`End tag "p" implied`,
+nested `<a>` tags, etc.). Those are content bugs in pre-existing pages, not
+a checker config problem.
+
 ## Installing dependencies
 
 ```sh

docs/2.0/docs/library/guides/integrate-tfc.md

@@ -212,14 +212,14 @@ Terraform requires an API token to communicate with Terraform Cloud (TFC) as a b
 
 Once TFC generates a token, add it to your local Terraform configuration file (`~/.terraformrc`) within a `credentials` block. Doing so will enable Terraform to authenticate with TFC when running remote operations.
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```hcl
  For TFE, substitute the custom hostname for your TFE host
 credentials "app.terraform.io" {
   token = "xxxxxxyyyyyyyyyzzzzzzzzzzzz"
 }
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 ### Generating the backend
 
@@ -348,7 +348,7 @@ Including all required inputs for the module in the generated `tfvars` file is e
 Once all configurations are in place, you can run `terragrunt init` to initialize the workspace (if it does not already exist) and then `terragrunt apply` to deploy the infrastructure. Terragrunt acts as a wrapper, invoking Terraform to perform the `plan` and `apply` stages on Terraform Cloud (TFC). During this process, the workflow will pause for confirmation between stages. However, if you run `terragrunt apply-all`, Terragrunt adds the `-auto-approve` flag, bypassing interactive approval and skipping the confirmation step.
 
 To begin, execute `terragrunt init`. This command generates the necessary backend configuration and `tfvars` file, establishing a connection to the remote backend. Below is an example output, with irrelevant details omitted for brevity.
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```bash
 $ terragrunt init
 [terragrunt] 2020/05/15 14:36:54 Reading Terragrunt config file at <redacted>/infrastructure-live/dev/us-east-1/sqs/terragrunt.hcl
@@ -428,7 +428,7 @@ queue_arn = arn:aws:sqs:us-east-1:0123456789012:example-name
 queue_name = example-name
 queue_url = https://sqs.us-east-1.amazonaws.com/0123456789012/example-name
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 TFC runs a plan first, waits for confirmation, and then runs apply. The confirmation can be entered either on the command line or in the UI. Once complete, the results are visible in the TFC UI:
 
 ![Viewing the Terragrunt command results in the TFC UI](/img/guides/working-with-code/tfc/tfc-terragrunt-results.png)

docs/2.0/docs/library/tutorials/deploying-your-first-gruntwork-module.md

@@ -323,7 +323,7 @@ def lambda_handler(event, context):
 ### Install dependencies
 
 Next, initialize the Go module and install Terratest as a dependency.
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```bash
 cd gw_module_guide/test
 go mod init github.com/<YOUR GITHUB USERNAME>/gw_module_guide
@@ -332,11 +332,11 @@ go get github.com/stretchr/testify/assert
 go get github.com/aws/aws-sdk-go/aws
 go mod tidy
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 ### Write the test
 
 Next, write the test. Define a single test called `TestLambdaCreated` that provisions an AWS Lambda function, verifies its creation, and then destroys the Lambda function. We’ll use built-in functionality in `Terratest` to generate random values and set variables that will be passed into Terraform.
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```go title=gw_module_guide/test/lambda_test.go
 package test
 
@@ -401,7 +401,7 @@ func TestLambdaCreated(t *testing.T) {
     assert.Equal(t, lambdaName, awsSDK.StringValue(function.Configuration.FunctionName))
 }
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 In this test, we first generate data to ensure that the test run creates resources with unique names. Next, we define the Terraform `options`, specifying the folder where the Terraform module resides and setting the values for the input variables. Then, we configure a `terraform destroy` operation, which will always run, regardless of the test status. We proceed by running `terraform init` and `terraform apply` to create the resources. Finally, we validate that the name of the AWS Lambda function created matches the expected name.
 

docs/2.0/docs/overview/concepts/gruntworkplatform.md

@@ -37,8 +37,8 @@ Gruntwork offers two main product packages:
 
 * [Infrastructure-Live](/2.0/docs/overview/concepts/infrastructure-live.md): An opinionated structure for IaC repositories that incorporates best practices for organizing OpenTofu code to maintain DRY principles at an enterprise scale.
 
-<!-- * [Catalog]  -- see DEV-628 -->
-<!-- Placeholder for networking/transit gateway details -->
+{/* * [Catalog]  -- see DEV-628 */}
+{/* Placeholder for networking/transit gateway details */}
 
 All components are designed with a focus on Terragrunt, OpenTofu/Terraform, GitHub, and AWS. Support for additional technologies may be introduced in the future.
 

docs/2.0/docs/patcher/guides/promotion-workflows.md

@@ -82,7 +82,7 @@ This file, similar to an OpenTofu plan file, is intended to be a temporary artif
 We recommend that you delete and `.gitignore` any spec files in your codebase.
 :::
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```yml
 name: Update Dev Dependencies
 on:
@@ -168,7 +168,7 @@ jobs:
           pull_request_title: "[Patcher] [dev] Update ${{ matrix.dependency.ID }}"
           pull_request_branch: "${{ env.PR_BRANCH_PREFIX }}${{ matrix.dependency.ID }}"
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 ### Setting up the stage step
 
 The `update-stage.yml` workflow file is nearly identical to `update-dev.yml`.

docs/2.0/docs/patcher/tutorials/applying-first-patch.md

@@ -72,9 +72,9 @@ Press `enter` to apply the update with Patcher:
 
 ![Patcher Update completion notice](/img/patcher/tutorials/patcher_update_complete.png)
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 You can now inspect the file system to verify the results of the patch. In this case, the update changed the version of `patcher-test` from `v0.10.3` to `v0.10.5` and added the required argument `sampleinput` to the unit. Commit and push these changes to your repository.  
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 ![Patcher Update completion notice](/img/patcher/tutorials/patcher_update_results.png)
 

docs/2.0/docs/patcher/tutorials/authoring-first-patch.md

@@ -25,7 +25,7 @@ For this tutorial, we will use the `patcher-test` module from the `gruntwork-io/
 Suppose you need to add a new required variable to the `patcher-test` module. 
 This change qualifies as a breaking change because consumers of your module must update their configurations to include the new variable. Without this update, OpenTofu will fail when planning or applying the infrastructure. 
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 Add the new `sampleinput` variable to `variables.tf`:
 
 ```hcl title="$$DIRECTORY$$/variables.tf"
@@ -35,7 +35,7 @@ variable "sampleinput" {
     default = "unset-value"
 }
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 ## Running `patcher generate` to template the patch
 
@@ -76,17 +76,17 @@ As the module maintainer, fill in the `<REPLACE_ME>` fields as needed:
 
 Because this breaking change is straightforward, we can use [`terrapatch`](https://github.com/gruntwork-io/terrapatch) to perform the required step: 
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```bash
 $ terrapatch add-module-argument $PATCHER_MODULE_ADDRESS sampleinput "\"samplevalue\""
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 `$PATCHER_MODULE_ADDRESS` gets populated when Patcher is run; it doesn't need to be set independently anywhere. 
 
 Once you have filled out the fields in the patch, it should look like this: 
 
-<!-- spell-checker: disable -->
+{/* spell-checker: disable */}
 ```yaml
 name: "Sample Breaking Change"
 description: A sample breaking change that adds a new argument
@@ -104,7 +104,7 @@ steps:
   - name:
     run: terrapatch add-module-argument $PATCHER_MODULE_ADDRESS sampleinput "\"samplevalue\""
 ```
-<!-- spell-checker: enable -->
+{/* spell-checker: enable */}
 
 ## Modifying `config.yaml`
 

docs/2.0/docs/pipelines/guides/extending-pipelines.md

@@ -115,7 +115,7 @@ This step-by-step guide outlines best practices for implementing custom actions:
 </TabItem>
 <TabItem value="gitlab" label="GitLab">
 
-<!-- TODO: Add support for GitLab custom actions -->
+{/* TODO: Add support for GitLab custom actions */}
 Contact Gruntwork support for assistance setting up custom actions for Gruntwork Pipelines on GitLab.
 
 </TabItem>
@@ -183,7 +183,7 @@ For example:
 </TabItem>
 <TabItem value="gitlab" label="GitLab">
 
-<!-- TODO: Add support for GitLab custom actions -->
+{/* TODO: Add support for GitLab custom actions */}
 
 </TabItem>
 </Tabs>