docs: fix link-checker file discovery (#10348)

### Description

The broken link checker lost its discovery of the MDX files so it wasn't
reporting issues. Also fixes some links that went broken while this
analysis was broken.

### Testing Instructions

[This
run](https://github.com/vercel/turborepo/actions/runs/14514917931/job/40721676278?pr=10348)
shows broken links being discovered again, so we know the root problem
is fixed.

---------

Co-authored-by: Chris Olszewski <[email protected]>

Author: anthonyshew

docs/link-checker/package.json

@@ -6,7 +6,7 @@
     "src"
   ],
   "scripts": {
-    "check-links": "tsx src/validate-docs-links.ts"
+    "check-links": "cd ../site/content && tsx ../../link-checker/src/validate-docs-links.ts"
   },
   "devDependencies": {
     "@types/node": "22.7.8",

docs/link-checker/src/markdown.ts

@@ -35,10 +35,16 @@ export type LinkError = {
 
 /** where to look for docs (.mdx files) */
 const DOCS_PATH = ".";
-const EXCLUDED_HASHES = ["top"];
+const EXCLUDED_HASHES: string[] = [
+  // Start: hashlinks created by Fumadocs
+  "create-turbo-config",
+  "add-package-manager",
+  "set-default-outputs",
+  // End: hashlinks created by Fumadocs
+];
 
 /** These paths exist, just not in our Markdown files */
-const EXCLUDED_PATHS = ["/api/remote-cache-spec", "/repo"];
+const EXCLUDED_PATHS = ["/api/remote-cache-spec", "/discord", "/docs/openapi"];
 
 const slugger = new GitHubSlugger();
 
@@ -86,7 +92,8 @@ const markdownProcessor = unified()
   });
 
 const filePathToUrl = (filePath: string): string =>
-  filePath.replace("docs", "/docs").replace(".mdx", "");
+  // "/" prefix makes it easier to compare internal links
+  "/" + filePath.replace(".mdx", "");
 
 const validateFrontmatter = (path: string, data: Record<string, unknown>) => {
   if (!data.title) {
@@ -190,6 +197,23 @@ const validateHashLink = (doc: Document, href: string) => {
     return [];
   }
 
+  if (
+    doc.headings.includes(
+      // Handles when the link has the experimental badge in it.
+      // Because we're parsing the raw document (not the rendered output), the JSX declaration is still present.
+      hashLink.replace(
+        "-experimental",
+        "-experimentalbadgeexperimentalexperimentalbadge"
+      )
+    )
+  ) {
+    console.warn(
+      `The hash link "${hashLink}" passed when including the <ExperimentalBadge /> JSX declaration.`
+    );
+    console.log();
+    return [];
+  }
+
   let linkError: LinkError = {
     type: "hash",
     href,
@@ -235,6 +259,9 @@ const traverseTreeAndValidateLinks = (
  */
 export const collectLinkErrors = async (): Promise<LinkError[]> => {
   const allMdxFilePaths = await getAllMdxFilePaths();
+  if (allMdxFilePaths.length === 0) {
+    throw new Error("No files were found for processing.");
+  }
 
   const documentMap = new Map(
     await Promise.all(allMdxFilePaths.map(prepareDocumentMapEntry))

docs/site/content/blog/turbo-1-10-0.mdx

@@ -57,7 +57,7 @@ Turborepo Generators allow you to add new code to your repository in a predictab
 Previously, you would need to copy code yourself and manually add dependencies to your new workspace. With Generators,
 we've automated the process of creating new workspaces and integrating them into your repository.
 
-You can [create a blank workspace from scratch](/docs/guides/generating-code#add-an-empty-workspace), [copy an existing workspace](/docs/guides/generating-code#copy-an-existing-workspace), or even create custom generators
+You can [create a blank workspace from scratch](/docs/guides/generating-code#add-an-empty-package), [copy an existing workspace](/docs/guides/generating-code#copy-an-existing-package), or even create custom generators
 for more control. Custom generators leverage [Plop](https://plopjs.com/) configurations, a common template definition strategy used in the JavaScript ecosystem.
 
 [Custom generators](/docs/guides/generating-code#custom-generators) can also be used to scaffold more granular sets of code than workspaces. You can significantly speed up tasks like:
@@ -122,7 +122,7 @@ To ensure that Turborepo includes these variables in your hash, use the `dotEnv`
   included in your hash.
 </Callout>
 
-For more, check out the [documentation](/docs/reference/configuration#dotenv).
+For more, check out the documentation.
 
 ### Environment Variable Wildcards
 
@@ -141,7 +141,7 @@ With wildcards, you can now specify patterns of variables to include in your has
 }
 ```
 
-For more, check out the [documentation](/docs/crafting-your-repository/using-environment-variables#wildcards).
+For more, check out the [documentation](/docs/reference/configuration#wildcards).
 
 ### Environment modes
 

docs/site/content/blog/turbo-1-11-0.mdx

@@ -93,7 +93,7 @@ We're putting a renewed effort towards ensuring our examples are kept up-to-date
 - Tooling like ESLint, Prettier, jest, and vitest pre-configured
 - Hot-reloading across packages
 
-[Use an example](/docs/getting-started/installation#start-with-an-example) to get started, or [browse the code directly](https://github.com/vercel/turbo/tree/main/examples) for more.
+[Use an example](/docs/getting-started/examples) to get started, or [browse the code directly](https://github.com/vercel/turbo/tree/main/examples) for more.
 
 ## Community
 

docs/site/content/blog/turbo-1-12-0.mdx

@@ -20,7 +20,7 @@ Turborepo 1.12 adds popular community-requested features and feedback improvemen
 
 - [**Colors in task logs**](#colors-in-task-logs): Colors from original shell logs used by default
 - [**Errors overhaul**](#errors-overhaul): Improved error messages for misconfigurations
-- [**Improved `inputs` ergonomics**](#improved---inputs-ergonomics): Use Turborepo's defaults with your input customizations
+- [**Improved `inputs` ergonomics**](#improved-inputs-ergonomics): Use Turborepo's defaults with your input customizations
 - [**Telemetry**](#telemetry): Help us focus on what matters most to Turborepo users
 
 We're also done cleaning up our migration to Rust in this release by removing the `--go-fallback` flag and shrinking the `turbo` binary by 58% compared to 1.11.

docs/site/content/blog/turbo-1-7-0.mdx

@@ -134,7 +134,7 @@ Also note that you will no longer need to specify `outputs: []` because not cach
 ## “Errors only” output mode for quieter logs
 
 To bring visibility to errors, community member [@dobesv](https://github.com/dobesv) contributed [a solution to only show errors instead of all logs from a task run](https://github.com/vercel/turbo/pull/2588). While debugging a pipeline, `--output-logs=errors-only` can be used to keep your signal-to-noise ratio high so you can focus on ensuring successful runs for your pipelines.
-This can be used as a [configuration option](/docs/reference/configuration#outputmode) or as a [CLI flag](/docs/reference/run#--output-logs)
+This can be used as a [configuration option](/docs/reference/configuration#outputlogs) or as a [CLI flag](/docs/reference/run#--output-logs-option)
 
 ```bash title="Terminal"
 turbo build --output-logs=errors-only

docs/site/content/blog/turbo-1-9-0.mdx

@@ -32,7 +32,7 @@ Turborepo 1.9 focuses on improving observability for your task runs to better un
 
 - [**Run Summaries**](#view-and-compare-task-runs): Use the `--summarize` flag to generate a summary of your task to compare against previous runs.
 - [**Easier Starters**](#bring-your-own-starter): Use the `--example` flag with `npx create-turbo` to start from official Turborepo examples or custom repositories.
-- [**Strict Environments** <ExperimentalBadge isLink={false} />](#strict-environments): Try enabling strict mode to restrict the environment variables your tasks have access to.
+- [**Strict Environments** <ExperimentalBadge isLink={false} />](#strict-environments-experimental): Try enabling strict mode to restrict the environment variables your tasks have access to.
 
 Update today by running `npx @turbo/codemod migrate`.
 
@@ -106,7 +106,7 @@ In `strict` mode, this configuration will only expose four environment variables
 
 `--env-mode` also supports `loose` and `infer`.
 
-Learn more in the [docs](/docs/reference/run#--env-mode).
+Learn more in the [docs](/docs/reference/run#--env-mode-option).
 
 ## Community
 

docs/site/content/blog/turbo-2-0.mdx

@@ -22,7 +22,7 @@ Turborepo 2.0 improves the developer experience of JavaScript and TypeScript rep
 - [**New terminal UI**](#new-terminal-ui): Interactive tasks and clearer logs
 - [**Watch Mode**](#watch-mode): Dependency-aware task watcher for any tooling in your repository
 - [**All-new documentation**](#all-new-documentation): Core monorepo concepts, refreshed API reference, and ecosystem tooling guides
-- **Licensing and maintenance updates**: Upgraded to MIT license and added [Long Term Support policy](/docs/getting-started/support-policy#lts-policy)
+- **Licensing and maintenance updates**: Upgraded to MIT license and added [Long Term Support policy](/docs/support-policy#lts-policy)
 
 Update today by running `npx @turbo/codemod migrate` or get started with `npx create-turbo@latest`.
 
@@ -136,7 +136,7 @@ Visit [the upgrading guide](/docs/crafting-your-repository/upgrading#upgrading-t
 
 ### Other
 
-- Minimum package manager version support for npm and pnpm updated to 8 ([Source](/docs/getting-started/support-policy#package-managers))
+- Minimum package manager version support for npm and pnpm updated to 8 ([Source](/docs/support-policy#package-managers))
 - Remove package manager argument from `create-turbo`, replaced by option ([PR](https://github.com/vercel/turbo/pull/8150))
 
 ## Community

docs/site/content/blog/turbo-2-3.mdx

@@ -86,7 +86,7 @@ This is more convenient than the equivalent command using `--filter` (`turbo run
 turbo run web#build docs#lint
 ```
 
-[Learn more in the documentation.](/docs/crafting-your-repository/running-tasks#filtering-by-package-name)
+[Learn more in the documentation.](/docs/crafting-your-repository/running-tasks#filtering-by-package)
 
 ## Simplified cache control
 

docs/site/content/docs/guides/tools/typescript.mdx

@@ -218,7 +218,7 @@ First, add a `check-types` script to any package that you want to check the type
 }
 ```
 
-Then, create a `check-types` task in `turbo.json`. From the [Configuring tasks guide](/docs/crafting-your-repository/configuring-tasks#dependent-tasks-that-can-be-ran-in-parallel), we can make the task run in parallel while respecting source code changes from other packages using a [Transit Node](/docs/core-concepts/package-and-task-graph#transit-nodes):
+Then, create a `check-types` task in `turbo.json`. From the [Configuring tasks guide](/docs/crafting-your-repository/configuring-tasks#dependent-tasks-that-can-be-run-in-parallel), we can make the task run in parallel while respecting source code changes from other packages using a [Transit Node](/docs/core-concepts/package-and-task-graph#transit-nodes):
 
 ```json title="./turbo.json"
 {

docs/site/content/docs/reference/configuration.mdx

@@ -99,7 +99,7 @@ Set/limit the maximum concurrency for task execution. Must be an integer greater
 
 - Use `1` to force serial execution (one task at a time).
 - Use `100%` to use all available logical processors.
-- This option is ignored if the [`--parallel`](#--parallel) flag is also passed.
+- This option is ignored if the [`--parallel`](/docs/reference/run#--parallel) flag is also passed.
 
 ```jsonc title="./turbo.json"
 {