(ci): Docs link checker. (#8958)

### Description Check link targets in docs so we know they are valid. No one likes an unexpected 404! ### Testing Instructions CI ### Note This script is [co-opted from Next.js](https://github.com/vercel/next.js/tree/canary/.github/actions/validate-docs-links). There might be some vestigials in it that are Next.js-specific, but I don't care enough to clean them out because the script is fast and works.
vercel · Aug 7, 2024 · c8fba08 · c8fba08
1 parent 9c03970
commit c8fba08
Show file tree

Hide file tree

Showing 24 changed files with 1,083 additions and 82 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,25 @@
+name: Docs checks
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - ".github/actions/validate-docs-links/**"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  validate-docs-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Setup Node"
+        uses: ./.github/actions/setup-node
+
+      - name: "Run link checker"
+        run: cd docs && pnpm run check-links
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/README.MD b/docs/README.MD
@@ -0,0 +1,9 @@
+# GitHub Action for Validating Documentation Links
+
+This action ensures that internal links in `.mdx` files in the `/docs/` directory are valid. It runs on every pull request that includes changes to these files.
+
+The action is triggered by the workflow defined in `.github/workflows/docs.yml`.
+
+## Usage
+
+pnpm check-links
diff --git a/docs/pack-docs/why-turbopack.mdx b/docs/pack-docs/why-turbopack.mdx
@@ -39,7 +39,7 @@ This more ‘lazy’ approach (only bundling assets when absolutely necessary) i
 
 esbuild doesn’t have a concept of ‘lazy’ bundling - it’s all-or-nothing, unless you specifically target only certain entry points.
 
-Turbopack’s development mode builds a minimal graph of your app’s imports and exports based on received requests and only bundles the minimal code necessary. Learn more in the [core concepts docs](/pack/docs/core-concepts#compiling-by-request).
+Turbopack’s development mode builds a minimal graph of your app’s imports and exports based on received requests and only bundles the minimal code necessary. Learn more in the [core concepts docs](/pack/docs/core-concepts).
 
 ## Summary
 

diff --git a/docs/package.json b/docs/package.json
@@ -0,0 +1,29 @@
+{
+  "private": true,
+  "type": "module",
+  "exports": "./dist/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "check-links": "tsx src/validate-docs-links.ts"
+  },
+  "devDependencies": {
+    "@types/github-slugger": "^1.3.0",
+    "@types/node": "^22.1.0",
+    "@vercel/ncc": "0.34.0",
+    "tsx": "^4.7.2",
+    "typescript": "5.1.6"
+  },
+  "dependencies": {
+    "@actions/core": "^1.10.0",
+    "@actions/github": "^5.1.1",
+    "github-slugger": "1.2.0",
+    "gray-matter": "4.0.2",
+    "rehype-raw": "4.0.1",
+    "remark-parse": "7.0.1",
+    "remark-rehype": "5.0.0",
+    "unified": "8.4.1",
+    "unist-util-visit": "2.0.0"
+  }
+}
diff --git a/docs/repo-docs/crafting-your-repository/caching.mdx b/docs/repo-docs/crafting-your-repository/caching.mdx
@@ -44,7 +44,7 @@ npx create-turbo@latest
 <Step>
 ### Run a build for the first time
 
-If you have [`turbo` installed globally](/repo/docs/getting-started/installation#installing-globally), run `turbo build` in your repository.
+If you have [`turbo` installed globally](/repo/docs/getting-started/installation#global-installation), run `turbo build` in your repository.
 
 Alternatively, you can run the `build` script in `package.json` using your package manager.
 
@@ -109,7 +109,7 @@ npx turbo link
 
 Now, when you run a task, Turborepo will automatically send the outputs of the task to Remote Cache. If you run the same task on a different machine that is also authenticated to your Remote Cache, it will hit cache the first time it runs the task.
 
-For information on how to connect your CI machines to Remote Cache, visit [the Constructing CI guide](/repo/docs/crafting-your-repository/constructing-ci#enable-remote-caching).
+For information on how to connect your CI machines to Remote Cache, visit [the Constructing CI guide](/repo/docs/crafting-your-repository/constructing-ci#enabling-remote-caching).
 
 <Callout type="info">
   By default, Turborepo uses [Vercel Remote
@@ -136,7 +136,7 @@ If you're running into errors with files not being available when you hit cache,
 
 Turborepo always captures the terminal outputs of your tasks, restoring those logs to your terminal from the first time that the task was ran.
 
-You can configure the verbosity of the replayed logs using [the `--output-logs` flag](/repo/docs/reference/run#--output-logs-option) or [`outputLogs` configuration option](/repo/docs/reference/configuration#outputmode).
+You can configure the verbosity of the replayed logs using [the `--output-logs` flag](/repo/docs/reference/run#--output-logs-option) or [`outputLogs` configuration option](/repo/docs/reference/configuration#outputlogs).
 
 ## Task inputs
 

diff --git a/docs/repo-docs/crafting-your-repository/developing-applications.mdx b/docs/repo-docs/crafting-your-repository/developing-applications.mdx
@@ -11,7 +11,7 @@ Developing applications in a monorepo unlocks powerful workflows, enabling you t
 Most development tasks are long-running tasks that watch for changes to your code. Turborepo enhances this experience with a powerful terminal UI and other capabilities like:
 
 - [Configuration for `dev` tasks](#configuring-development-tasks)
-- [Interacting with tasks](#using-the-terminal-ui)
+- [Interacting with tasks](#interacting-with-tasks)
 - [Watch Mode](#watch-mode)
 - [Running setup scripts](#running-setup-tasks-before-dev)
 - [Filtering tasks to run a subset of your packages](#running-a-specific-application)
@@ -42,6 +42,16 @@ You can now run your `dev` task to start your development scripts in parallel:
 turbo dev
 ```
 
+### Interacting with tasks
+
+Some scripts allow you to type into them using `stdin` for interactive inputs. Using [the terminal ui](https://turbo.build/repo/docs/reference/configuration#ui), you can select a task, enter it, and use `stdin` as you typically would.
+
+<Callout type="good-to-know">
+  A task must be
+  [interactive](https://turbo.build/repo/docs/reference/configuration#interactive)
+  to enable this functionality.
+</Callout>
+
 ### Running setup tasks before `dev`
 
 You may also want to run scripts that set up your development environment or pre-build packages. You can make sure those tasks run before the `dev` task with `dependsOn`:

diff --git a/docs/repo-docs/crafting-your-repository/running-tasks.mdx b/docs/repo-docs/crafting-your-repository/running-tasks.mdx
@@ -68,7 +68,7 @@ calling `turbo`.
 
 ## Using global `turbo`
 
-[Installing `turbo` globally](/repo/docs/getting-started/installation#installing-globally) lets you run commands directly from your terminal. This improves your local development experience since it makes it easier to run exactly what you need, when you need it.
+[Installing `turbo` globally](/repo/docs/getting-started/installation#global-installation) lets you run commands directly from your terminal. This improves your local development experience since it makes it easier to run exactly what you need, when you need it.
 
 Additionally, global `turbo` is useful in your CI pipelines, giving you maximum control of exactly which tasks to run at each point in your pipeline.
 
@@ -93,7 +93,7 @@ In [the documentation for the `run` subcommand](/repo/docs/reference/run), you'l
 
 - **Variations of your most common commands**: The `build` script in `package.json` has the most utility when it is `turbo build` - but you might only be interested in a specific package at the moment. You can quickly filter for the specific package you're interested in using `turbo build --filter=@repo/ui`.
 - **One-off commands**: Commands like `turbo build --dry` aren't needed often so you likely won't create a script in your `package.json` for it. Instead, you can run it directly in your terminal whenever you need it.
-- **Overriding `turbo.json` configuration**: Some CLI flags have an equivalent in `turbo.json` that you can override. For instance, you may have a `turbo build` command configured to use [`"outputLogs": "full"` in `turbo.json`](/repo/docs/reference/configuration#outputmode) - but you're only interested in seeing errors at the moment. Using global `turbo`, you can use `turbo lint --output-logs=errors-only` to only show errors.
+- **Overriding `turbo.json` configuration**: Some CLI flags have an equivalent in `turbo.json` that you can override. For instance, you may have a `turbo build` command configured to use [`"outputLogs": "full"` in `turbo.json`](/repo/docs/reference/configuration#outputlogs) - but you're only interested in seeing errors at the moment. Using global `turbo`, you can use `turbo lint --output-logs=errors-only` to only show errors.
 
 ## Running multiple tasks
 

diff --git a/docs/repo-docs/crafting-your-repository/structuring-a-repository.mdx b/docs/repo-docs/crafting-your-repository/structuring-a-repository.mdx
@@ -111,6 +111,7 @@ Below, the structural elements of `create-turbo` that make it a valid workspace
 
 <Steps>
 <Step>
+
 #### Declaring directories for packages
 
 First, your package manager needs to describe the locations of your packages. We recommend starting with splitting your packages into `apps/` for applications and services and `packages/` for everything else, like libraries and tooling.
@@ -162,6 +163,7 @@ If you'd like to group packages by directory, you can do this using globs like `
 </Step>
 
 <Step>
+
 #### `package.json` in each package
 
 In the directory of the package, there must be a `package.json` to make the package discoverable to your package manager and `turbo`. The [requirements for the `package.json` of a package](#anatomy-of-a-package) are below.

diff --git a/docs/repo-docs/guides/single-package-workspaces.mdx b/docs/repo-docs/guides/single-package-workspaces.mdx
@@ -42,7 +42,7 @@ Install `turbo` into your application:
 
 ### Running a `package.json` script using global `turbo` (optional)
 
-For even faster developer workflows, you can [install `turbo` globally](/repo/docs/getting-started/installation#installing-globally), too, and run commands directly from the command line.
+For even faster developer workflows, you can [install `turbo` globally](/repo/docs/getting-started/installation#global-installation), too, and run commands directly from the command line.
 
 Once installed, you can run `turbo build` and Turborepo will run your `build` script from `package.json`. Running `turbo build` again will hit the cache.
 

diff --git a/docs/repo-docs/guides/tools/eslint.mdx b/docs/repo-docs/guides/tools/eslint.mdx
@@ -201,7 +201,7 @@ By adding `@repo/eslint-config/next.js` to our `extends` array, we're telling ES
 
 ### Summary
 
-This setup ships by default when you [create a new monorepo](/repo/docs/getting-started/create-new) with `npx create-turbo@latest`. You can also look at [our basic example](https://github.com/vercel/turbo/tree/main/examples/basic) to see a working version.
+This setup ships by default when you [create a new monorepo](/repo/docs/crafting-your-repository#from-zero-to-turbo) with `npx create-turbo@latest`. You can also look at [our basic example](https://github.com/vercel/turbo/tree/main/examples/basic) to see a working version.
 
 ## Setting up a `lint` task
 

diff --git a/docs/repo-docs/guides/tools/jest.mdx b/docs/repo-docs/guides/tools/jest.mdx
@@ -154,7 +154,7 @@ Inside the root `turbo.json`:
 }
 ```
 
-You can now either run this task using [global `turbo`](/repo/docs/getting-started/installation#installing-globally) as `turbo test:watch` or from a script in your root `package.json`:
+You can now either run this task using [global `turbo`](/repo/docs/getting-started/installation#global-installation) as `turbo test:watch` or from a script in your root `package.json`:
 
 <Tabs items={["Global turbo", "./package.json"]}>
 <Tab value="Global turbo">

diff --git a/docs/repo-docs/guides/tools/prisma.mdx b/docs/repo-docs/guides/tools/prisma.mdx
@@ -50,6 +50,7 @@ Run your package manager's install step to install the new dependencies.
 
 </Step>
 <Step>
+
 ## Run `prisma init`
 
 `cd` into `packages/database`:
@@ -72,6 +73,7 @@ Once you've got a database connected and have a few data tables to work with, yo
 
 </Step>
 <Step>
+
 ## Create scripts
 
 Let's add some scripts to the `package.json` inside `packages/database`:
@@ -111,6 +113,7 @@ Now, run `turbo db:push db:generate` from the root of our repository to automati
 </Step>
 
 <Step>
+
 ## Exporting your client
 
 Next, export the `@prisma/client` so it can used in your applications. Let's add an `index.ts` file to `packages/database`:

diff --git a/docs/repo-docs/guides/tools/storybook.mdx b/docs/repo-docs/guides/tools/storybook.mdx
@@ -160,6 +160,7 @@ pnpm install @repo/ui --filter=storybook
 </Step>
 
 <Step>
+
 ### Set up a story for your Button component
 
 Delete the stories and components found in `src/stories` that were created by the Storybook scaffolding tool. You will be making your own.

diff --git a/docs/repo-docs/guides/tools/vitest.mdx b/docs/repo-docs/guides/tools/vitest.mdx
@@ -82,7 +82,7 @@ Inside the root `turbo.json`:
 }
 ```
 
-You can now either run this task using [global `turbo`](/repo/docs/getting-started/installation#installing-globally) as `turbo test:watch` or from a script in your root `package.json`:
+You can now either run this task using [global `turbo`](/repo/docs/getting-started/installation#global-installation) as `turbo test:watch` or from a script in your root `package.json`:
 
 <Tabs items={["Global turbo", "./package.json"]}>
 <Tab value="Global turbo">

diff --git a/docs/repo-docs/reference/bin.mdx b/docs/repo-docs/reference/bin.mdx
@@ -5,6 +5,6 @@ description: API reference for the `turbo bin` command
 
 Get the path to the `turbo` binary.
 
-When using [**global `turbo`**](/repo/docs/getting-started/installation#installing-globally), this will be the path to the global `turbo` binary. You're likely to see a path to the global directory of the package manager you used to install `turbo`.
+When using [**global `turbo`**](/repo/docs/getting-started/installation#global-installation), this will be the path to the global `turbo` binary. You're likely to see a path to the global directory of the package manager you used to install `turbo`.
 
-When using [**local `turbo`**](/repo/docs/getting-started/installation#installing-per-repository), this will be the path to the local `turbo` binary. When `turbo` is installed in your repository, it is likely to be a path to `node_modules`.
+When using [**local `turbo`**](/repo/docs/getting-started/installation#repository-installation), this will be the path to the local `turbo` binary. When `turbo` is installed in your repository, it is likely to be a path to `node_modules`.
diff --git a/docs/repo-docs/reference/configuration.mdx b/docs/repo-docs/reference/configuration.mdx
@@ -111,7 +111,7 @@ To help with incremental migration or in situations where you can't use the `pac
 
 <Callout type="info">
   You may also opt out of this check via
-  [`flag`](/repo/docs/reference/run#dangerously-disable-package-manager-check)
+  [`flag`](/repo/docs/reference/run#--dangerously-disable-package-manager-check)
   or the
   [`TURBO_DANGEROUSLY_DISABLE_PACKAGE_MANAGER_CHECK`](https://turbo.build/repo/docs/reference/system-environment-variables)
   environment variable.
@@ -375,7 +375,7 @@ the special string `$TURBO_DEFAULT$` within the `inputs` array to restore `turbo
 
 Default: `full`
 
-Set output logging verbosity. Can be overridden by the [`--output-logs`](/repo/docs/reference/run#--output-logs) CLI option.
+Set output logging verbosity. Can be overridden by the [`--output-logs`](/repo/docs/reference/run#--output-logs-option) CLI option.
 
 | Option        | Description                       |
 | ------------- | --------------------------------- |

diff --git a/docs/repo-docs/reference/run.mdx b/docs/repo-docs/reference/run.mdx
@@ -332,7 +332,7 @@ Passing `--no-daemon` instructs `turbo` to avoid using or creating the standalon
 
 Default: `full`
 
-Set type of output logging, overriding [`outputLogs`](/repo/docs/reference/configuration#outputmode) if it's defined in `turbo.json`.
+Set type of output logging, overriding [`outputLogs`](/repo/docs/reference/configuration#outputlogs) if it's defined in `turbo.json`.
 
 ```bash title="Terminal"
 turbo run build --output-logs=errors-only
-Original file line number
+Diff line change
@@ Expand Up @@
     <Steps>
     <Step>
     #### Declaring directories for packages
     First, your package manager needs to describe the locations of your packages. We recommend starting with splitting your packages into `apps/` for applications and services and `packages/` for everything else, like libraries and tooling.
@@ Expand Down Expand Up @@
     </Step>
     <Step>
     #### `package.json` in each package
     In the directory of the package, there must be a `package.json` to make the package discoverable to your package manager and `turbo`. The [requirements for the `package.json` of a package](#anatomy-of-a-package) are below.
@@ Expand Down @@