mochajs · mark-wiemer · Sep 1, 2025 · Aug 17, 2025 · Aug 17, 2025
diff --git a/docs-next/astro.config.ts b/docs-next/astro.config.ts
@@ -1,8 +1,22 @@
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
+import { visit } from "unist-util-visit";
+
+const base = "/next";
+
+/** Prepend base URL to non-`/api` absolute links */
+const rewriteLinks = ({ base }: { base: string }) => {
+  return (tree: any) => {
+    visit(tree, "link", (node) => {
+      if (node.url.startsWith("/") && !node.url.startsWith("/api")) {
+        node.url = base + node.url;
+      }
+    });
+  };
+};
 
 export default defineConfig({
-  base: "/next",
+  base,
   integrations: [
     starlight({
       components: {
@@ -122,4 +136,7 @@ export default defineConfig({
       title: "Mocha",
     }),
   ],
+  markdown: {
+    remarkPlugins: [[rewriteLinks, { base }]],
+  },
 });
diff --git a/docs-next/package-lock.json b/docs-next/package-lock.json
diff --git a/docs-next/package.json b/docs-next/package.json
@@ -3,14 +3,14 @@
   "type": "module",
   "version": "0.0.1",
   "scripts": {
-    "generate": "node ../docs/_data/supporters.js --write-supporters-json",
+    "astro": "astro",
+    "build": "astro check && astro build",
+    "build-with-old": "npm run generate && npm run build -- --outDir ../docs/_site/next",
     "dev": "astro dev",
-    "start": "astro dev",
     "docs": "cd .. && npm i && cd docs-next && npm run generate && npm run build",
-    "build": "astro check && astro build",
+    "generate": "node ../docs/_data/supporters.js --write-supporters-json",
     "preview": "astro preview",
-    "build-with-old": "npm run generate && npm run build -- --outDir ../docs/_site/next",
-    "astro": "astro"
+    "start": "astro dev"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.4",
@@ -21,6 +21,7 @@
     "needle": "^3.3.1",
     "sharp": "^0.32.5",
     "starlight-package-managers": "^0.7.0",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "unist-util-visit": "^5.0.0"
   }
 }
diff --git a/docs-next/src/content/docs/declaring/dynamic-tests.mdx b/docs-next/src/content/docs/declaring/dynamic-tests.mdx
@@ -62,7 +62,7 @@ describe("add()", function () {
 
 With `top-level await` you can collect your test data in a dynamic and asynchronous way while the test file is being loaded.
 
-See also [`--delay`](/next/features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.
+See also [`--delay`](/features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.
 
 ```js
 // testfile.mjs

diff --git a/docs-next/src/content/docs/declaring/exclusive-tests.mdx b/docs-next/src/content/docs/declaring/exclusive-tests.mdx
@@ -4,7 +4,7 @@ title: Exclusive Tests
 ---
 
 :::caution
-Exclusive tests are incompatible with [parallel mode](/next/features/parallel-mode).
+Exclusive tests are incompatible with [parallel mode](/features/parallel-mode).
 :::
 
 The exclusivity feature allows you to run _only_ the specified suite or test-case

diff --git a/docs-next/src/content/docs/declaring/inclusive-tests.mdx b/docs-next/src/content/docs/declaring/inclusive-tests.mdx
@@ -5,7 +5,7 @@ title: Inclusive Tests
 
 This feature is the inverse of `.only()`.
 By appending `.skip()`, you may tell Mocha to ignore test case(s).
-Anything skipped will be marked as [pending](/next/declaring/pending-tests) and reported as such.
+Anything skipped will be marked as [pending](/declaring/pending-tests) and reported as such.
 Here's an example of skipping an individual test:
 
 ```js
@@ -56,7 +56,7 @@ it('should only test in the correct environment', function() {
 });
 ```
 
-The above test will be reported as [pending](/next/declaring/pending-tests).
+The above test will be reported as [pending](/declaring/pending-tests).
 It's also important to note that calling `this.skip()` will effectively _abort_ the test.
 
 :::tip[Best practice]

diff --git a/docs-next/src/content/docs/declaring/pending-tests.mdx b/docs-next/src/content/docs/declaring/pending-tests.mdx
@@ -17,4 +17,4 @@ describe("Array", function () {
 Pending tests will be included in the test results and marked as pending.
 A pending test is not considered a failed test.
 
-Read the [inclusive tests section](/next/declaring/inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.
+Read the [inclusive tests section](/declaring/inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.
diff --git a/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx b/docs-next/src/content/docs/explainers/nodejs-native-esm-support.mdx
@@ -26,9 +26,9 @@ More information can be found in the [Node.js documentation](https://nodejs.org/
 
 ### Current Limitations
 
-- [Watch mode](/next/running/cli#--watch--w) does not support ES Module test files
-- [Custom reporters](/next/reporters/third-party) and [custom interfaces](/next/interfaces/third-party) can only be CommonJS files
-- [Configuration file](/next/running/configuring) can only be a CommonJS file (`.mocharc.js` or `.mocharc.cjs`)
+- [Watch mode](/running/cli#--watch--w) does not support ES Module test files
+- [Custom reporters](/reporters/third-party) and [custom interfaces](/interfaces/third-party) can only be CommonJS files
+- [Configuration file](/running/configuring) can only be a CommonJS file (`.mocharc.js` or `.mocharc.cjs`)
 - Mocha in Node.js version 24.4.0 or older [silently ignored top level errors in ESM files](https://github.com/mochajs/mocha/issues/5396).
   If you cannot upgrade to a newer Node.js version, you can add `--no-experimental-require-module` to the `NODE_OPTIONS` environment variable.
 - When using module-level mocks via libs like `proxyquire`, `rewiremock` or `rewire`, hold off on using ES modules for your test files.

diff --git a/docs-next/src/content/docs/explainers/run-cycle-overview.mdx b/docs-next/src/content/docs/explainers/run-cycle-overview.mdx
@@ -11,35 +11,35 @@ In a browser, test files are loaded by `<script>` tags, and calling `mocha.run()
 
 1. User (that's you) executes `mocha`
 2. Loads options from config files, if present
-3. Mocha processes any command-line options provided (see section on [configuration merging](/next/running/configuring#merging) for details)
+3. Mocha processes any command-line options provided (see section on [configuration merging](/running/configuring#merging) for details)
 4. If known flags for the `node` executable are found:
    1. Mocha will spawn `node` in a child process, executing itself with these flags
    2. Otherwise, Mocha does not spawn a child process
 5. Mocha loads modules specified by `--require`
-   1. If a file loaded this way contains known Mocha-specific exports (e.g., [root hook plugins](/next/features/root-hook-plugins)), Mocha "registers" these
+   1. If a file loaded this way contains known Mocha-specific exports (e.g., [root hook plugins](/features/root-hook-plugins)), Mocha "registers" these
    2. If not, Mocha ignores any exports of a `--require`'d module
 6. Mocha validates any custom reporters or interfaces which were loaded via `--require` or otherwise
 7. Mocha _discovers_ test files; when given no files or directories, it finds files with extensions `.js`, `.mjs` or `.cjs` in the `test` directory (but not its children), relative to the current working directory
-8. The (default) [bdd interface](/next/interfaces/bdd) loads the test files _in no particular order_, which are given an interface-specific `global` context (this is how, e.g., `describe()` ends up as a global in a test file)
+8. The (default) [bdd interface](/interfaces/bdd) loads the test files _in no particular order_, which are given an interface-specific `global` context (this is how, e.g., `describe()` ends up as a global in a test file)
    1. When a test file is loaded, Mocha executes all of its suites and finds--_but does not execute_--any hooks and tests therein.
    2. Top-level hooks, tests and suites are all made members of an "invisible" _root suite_; there is only _one_ root suite for the entire process
-9. Mocha runs [global setup fixtures](/next/features/global-fixtures#global-setup-fixtures), if any
+9. Mocha runs [global setup fixtures](/features/global-fixtures#global-setup-fixtures), if any
 10. Starting with the "root" suite, Mocha executes:
-11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))
+11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/features/root-hook-plugins))
 12. For each test, Mocha executes:
     1. Any "before each" hooks
     2. The test (and reports the result)
     3. Any "after each" hooks
 13. If the current suite has a child suite, repeat the steps in 10. for each child suite; each child suite _inherits_ any "before each" and "after each" hooks defined in its parent
-14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))
+14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/features/root-hook-plugins))
 15. Mocha prints a final summary/epilog, if applicable
-16. Mocha runs [global teardown fixtures](/next/features/global-fixtures#global-teardown-fixtures), if any
+16. Mocha runs [global teardown fixtures](/features/global-fixtures#global-teardown-fixtures), if any
 
 ## Parallel Mode
 
 1. Repeat steps 1 through 6 from [Serial Mode](#serial-mode) above, skipping reporter validation
 2. All test files found are put into a queue (they are _not_ loaded by the main process)
-3. Mocha runs [global setup fixtures](/next/features/global-fixtures#global-setup-fixtures), if any
+3. Mocha runs [global setup fixtures](/features/global-fixtures#global-setup-fixtures), if any
 4. Mocha creates a pool of subprocesses ("workers")
 5. _Immediately before_ a worker runs the first test it receives, the worker "bootstraps" itself by:
    1. Loading all `--require`'d modules
@@ -52,4 +52,4 @@ In a browser, test files are loaded by `<script>` tags, and calling `mocha.run()
 9. When the worker completes the test file, buffered results are returned to the main process, which then gives them to the user-specified reporter (`spec` by default)
 10. The worker makes itself available to the pool; the pool gives the worker another test file to run, if any remain
 11. Mocha prints a final summary/epilog, if applicable
-12. Mocha runs [global teardown fixtures](/next/features/global-fixtures#global-teardown-fixtures), if any
+12. Mocha runs [global teardown fixtures](/features/global-fixtures#global-teardown-fixtures), if any
diff --git a/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx b/docs-next/src/content/docs/explainers/test-fixture-decision-tree.mdx
@@ -3,7 +3,7 @@ description: Helping you decide which API(s) to use for your test fixtures.
 title: Test Fixture Decision Tree
 ---
 
-This flowchart will help you decide when to use [hooks](/next/features/hooks), [root hook plugins](/next/features/root-hook-plugins) or [global fixtures](/next/features/global-fixtures).
+This flowchart will help you decide when to use [hooks](/features/hooks), [root hook plugins](/features/root-hook-plugins) or [global fixtures](/features/global-fixtures).
 
 import FixtureWizard from "../../../components/FixtureWizard.astro";
 

diff --git a/docs-next/src/content/docs/features/global-fixtures.mdx b/docs-next/src/content/docs/features/global-fixtures.mdx
@@ -6,7 +6,7 @@ title: Global Fixtures
 :::note[New in v8.2.0]
 :::
 
-At first glance, _global fixtures_ seem similar to [root hook plugins](/next/features/root-hook-plugins).
+At first glance, _global fixtures_ seem similar to [root hook plugins](/features/root-hook-plugins).
 However, unlike root hooks, global fixtures:
 
 1. Are _guaranteed_ to execute _once and only once_
@@ -44,7 +44,7 @@ export async function mochaGlobalSetup() {
 To use it, load this file when running Mocha via `mocha --require fixtures.cjs` (or whatever you have named the file).
 
 :::tip
-Remember: you can define "requires" in a [configuration file](/next/running/configuring).
+Remember: you can define "requires" in a [configuration file](/running/configuring).
 :::
 
 Now, before Mocha loads and runs your tests, it will execute the above global setup fixture, starting a server for testing.
@@ -96,7 +96,7 @@ You could be clever and try to get around this restriction by assigning somethin
 It's probably best to play by the rules!
 :::
 
-Instead, use the global fixture to _start_ the database, and use [root hook plugins](/next/features/root-hook-plugins) or plain old [hooks](/next/features/hooks) to create a connection.
+Instead, use the global fixture to _start_ the database, and use [root hook plugins](/features/root-hook-plugins) or plain old [hooks](/features/hooks) to create a connection.
 
 Here's an example of using global fixtures and "before all" hooks to get the job done.
 Note that we do not reference the `server` object anywhere in our tests!

diff --git a/docs-next/src/content/docs/features/hooks.mdx b/docs-next/src/content/docs/features/hooks.mdx
@@ -87,12 +87,12 @@ describe("Connection", function () {
 
 A hook defined at the top scope of a test file (outside of a suite) is a _root hook_.
 
-As of v8.0.0, [Root Hook Plugins](/next/features/root-hook-plugins) are the preferred mechanism for setting root hooks.
+As of v8.0.0, [Root Hook Plugins](/features/root-hook-plugins) are the preferred mechanism for setting root hooks.
 
 ## Delayed Root Suite
 
 :::caution
-Delayed root suites are incompatible with [parallel mode](/next/features/parallel-mode).
+Delayed root suites are incompatible with [parallel mode](/features/parallel-mode).
 :::
 
 If you need to perform asynchronous operations before any of your suites are run (e.g. for dynamically generating tests), you may delay the root suite.

diff --git a/docs-next/src/content/docs/features/parallel-mode.mdx b/docs-next/src/content/docs/features/parallel-mode.mdx
@@ -6,7 +6,7 @@ title: Parallel Mode
 :::note[New in v8.0.0]
 :::
 
-Depending on the number and nature of your tests, you may find a significant performance benefit when running tests in parallel (using the [`--parallel`](/next/running/cli#--parallel--p) flag).
+Depending on the number and nature of your tests, you may find a significant performance benefit when running tests in parallel (using the [`--parallel`](/running/cli#--parallel--p) flag).
 
 Parallel tests should work out-of-the box for many use cases.
 However, you must be aware of some important implications of the behavior.
@@ -19,9 +19,9 @@ Authors of third-party libraries built on Mocha should read this!
 
 Due to the nature of the following reporters, they cannot work when running tests in parallel:
 
-- [`json-stream`](/next/reporters/json-stream)
-- [`markdown`](/next/reporters/markdown)
-- [`progress`](/next/reporters/progress)
+- [`json-stream`](/reporters/json-stream)
+- [`markdown`](/reporters/markdown)
+- [`progress`](/reporters/progress)
 
 These reporters expect Mocha to know _how many tests it plans to run_ before execution.
 This information is unavailable in parallel mode, as test files are loaded only when they are about to be run.
@@ -38,7 +38,7 @@ This is for the same reason as the incompatible reporters noted above: in parall
 
 Suggested workarounds:
 
-1. Use [`--grep`](/next/running/cli#--grep-regexp--g-regexp) or [`--fgrep`](/next/running/cli#--fgrep-string--f-string) instead; it's not particularly efficient, but it will work.
+1. Use [`--grep`](/running/cli#--grep-regexp--g-regexp) or [`--fgrep`](/running/cli#--fgrep-string--f-string) instead; it's not particularly efficient, but it will work.
 1. Don't use parallel mode.
    Likely, you won't be running very many exclusive tests, so you won't see a great benefit from parallel mode anyhow.
 
@@ -52,15 +52,15 @@ In parallel mode, Mocha does not guarantee the order in which test files will ru
 
 Because of this, the following options, which depend on order, _cannot be used_ in parallel mode:
 
-- [`--file`](/next/running/cli#--file-file)
-- [`--sort`](/next/running/cli#--sort--s)
-- [`--delay`](/next/running/cli#--delay)
+- [`--file`](/running/cli#--file-file)
+- [`--sort`](/running/cli#--sort--s)
+- [`--delay`](/running/cli#--delay)
 
 ## Test Duration Variability
 
 Running tests in parallel mode will naturally use more system resources.
 The OS may take extra time to schedule and complete some operations, depending on system load.
-For this reason, the timeouts of _individual tests_ may need to be increased either [globally](/next/running/cli#--timeout-ms--t-ms) or [otherwise](/next/features/timeouts).
+For this reason, the timeouts of _individual tests_ may need to be increased either [globally](/running/cli#--timeout-ms--t-ms) or [otherwise](/features/timeouts).
 
 ## "Bail" is "Best Effort"
 
@@ -112,9 +112,9 @@ Here are a couple suggested workarounds:
 
 1. `require('./setup.js')` or `import './setup.js'` at the top of every test file.
    Best avoided for those averse to boilerplate.
-1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](/next/features/root-hook-plugins) system.
+1. _Recommended_: Define root hooks in a "required" file, using the [Root Hook Plugin](/features/root-hook-plugins) system.
 
-If you need to run some code _once and only once_, use a [global fixture](/next/features/global-fixtures) instead.
+If you need to run some code _once and only once_, use a [global fixture](/features/global-fixtures) instead.
 
 ## No Browser Support
 
@@ -127,15 +127,15 @@ If a third-party reporter does not work in parallel mode (but otherwise works in
 
 ## Troubleshooting Parallel Mode
 
-If you find your tests don't work properly when run with [`--parallel`](/next/running/cli#--parallel--p), either shrug and move on, or use this handy-dandy checklist to get things working:
+If you find your tests don't work properly when run with [`--parallel`](/running/cli#--parallel--p), either shrug and move on, or use this handy-dandy checklist to get things working:
 
 - ✅ Ensure you are using a [supported reporter](#reporter-limitations).
 - ✅ Ensure you are not using [other unsupported flags](#file-order-is-non-deterministic).
-- ✅ Double-check your [config file](/next/running/configuring); options set in config files will be merged with any command-line option.
+- ✅ Double-check your [config file](/running/configuring); options set in config files will be merged with any command-line option.
 - ✅ Look for [root hooks](#root-hooks-are-not-global) in your tests.
-  Move them into a [Root Hook Plugin](/next/features/root-hook-plugins).
+  Move them into a [Root Hook Plugin](/features/root-hook-plugins).
 - ✅ Do any assertion, mock, or other test libraries you're consuming use root hooks? They may need to be [migrated](#migrating-a-library-to-use-root-hook-plugins) for compatibility with parallel mode.
-- ✅ If tests are unexpectedly timing out, you may need to increase the default test timeout (via [`--timeout`](/next/running/cli#--timeout-ms--t-ms))
+- ✅ If tests are unexpectedly timing out, you may need to increase the default test timeout (via [`--timeout`](/running/cli#--timeout-ms--t-ms))
 - ✅ Ensure your tests do not depend on being run in a specific order.
 - ✅ Ensure your tests clean up after themselves; remove temp files, handles, sockets, etc.
   Don't try to share state or resources between test files.
@@ -149,7 +149,7 @@ Free-tier cloud CI services may not provide a suitable multi-core container or V
 Regarding expected performance gains in CI: your mileage may vary.
 It may help to use a conditional in a `.mocharc.js` to check for `process.env.CI`, and adjust the job count as appropriate.
 
-It's unlikely (but not impossible) to see a performance gain from a [job count](/next/running/cli#--jobs-count--j-count) _greater than_ the number of available CPU cores.
+It's unlikely (but not impossible) to see a performance gain from a [job count](/running/cli#--jobs-count--j-count) _greater than_ the number of available CPU cores.
 That said, _play around with the job count_--there's no one-size-fits all, and the unique characteristics of your tests will determine the optimal number of jobs; it may even be that fewer is faster!
 
 ## Parallel Mode Worker IDs