docs: fix links in new site (#5416)

Author: mark-wiemer

docs-next/README.md

@@ -1,25 +1,14 @@
-# Mocha Docs vNext: Built on Astro Starlight
+# Mocha Docs: Built on Astro Starlight
 
-After `cd`ing into this directory:
+This is the new site, hosted at https://mochajs.org/next and built with [Astro Starlight](https://starlight.astro.build). For details on how to build alongside the old site, see the `docs` directory.
+
+To run this site alone:
 
 ```shell
+cd docs-next
 npm i
 npm run generate
 npm run dev
 ```
 
-To merge with the old site:
-
-```shell
-npm i
-npm run build-with-old
-```
-
-To preview the old and new site:
-
-```shell
-cd .. # back to root dir
-npm run docs:preview
-```
-
-The new site will be at `http://localhost:8080/next`
+However, note that relative links may resolve with `dev` but fail with `build` and `preview` (see https://github.com/mochajs/mocha/issues/5415).

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`](../features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.
+See also [`--delay`](/next/features/hooks#delayed-root-suite) for CommonJS modules without `top-level await`.
 
 ```js
 // testfile.mjs

docs-next/src/content/docs/declaring/exclusive-tests.mdx

@@ -4,7 +4,7 @@ title: Exclusive Tests
 ---
 
 :::caution
-Exclusive tests are incompatible with [parallel mode](../features/parallel-mode).
+Exclusive tests are incompatible with [parallel mode](/next/features/parallel-mode).
 :::
 
 The exclusivity feature allows you to run _only_ the specified suite or test-case

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](./pending-tests) and reported as such.
+Anything skipped will be marked as [pending](/next/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](./pending-tests).
+The above test will be reported as [pending](/next/declaring/pending-tests).
 It's also important to note that calling `this.skip()` will effectively _abort_ the test.
 
 :::tip[Best practice]

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](./inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.
+Read the [inclusive tests section](/next/declaring/inclusive-tests) for an example of conditionally marking a test as pending via `this.skip()`.

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](../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`)
+- [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`)
 - 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.

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](../running/configuring#merging) for details)
+3. Mocha processes any command-line options provided (see section on [configuration merging](/next/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](../features/root-hook-plugins)), Mocha "registers" these
+   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
    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](../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](/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)
    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](../features/global-fixtures#global-setup-fixtures), if any
+9. Mocha runs [global setup fixtures](/next/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](../features/root-hook-plugins))
+11. Any "before all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/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](../features/root-hook-plugins))
+14. Any "after all" hooks (for the _root_ suite, this only happens once; see [root hook plugins](/next/features/root-hook-plugins))
 15. Mocha prints a final summary/epilog, if applicable
-16. Mocha runs [global teardown fixtures](../features/global-fixtures#global-teardown-fixtures), if any
+16. Mocha runs [global teardown fixtures](/next/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](../features/global-fixtures#global-setup-fixtures), if any
+3. Mocha runs [global setup fixtures](/next/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](../features/global-fixtures#global-teardown-fixtures), if any
+12. Mocha runs [global teardown fixtures](/next/features/global-fixtures#global-teardown-fixtures), if any

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](../features/hooks), [root hook plugins](../features/root-hook-plugins) or [global fixtures](../features/global-fixtures).
+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).
 
 import FixtureWizard from "../../../components/FixtureWizard.astro";
 

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](./root-hook-plugins).
+At first glance, _global fixtures_ seem similar to [root hook plugins](/next/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](../running/configuring).
+Remember: you can define "requires" in a [configuration file](/next/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](./root-hook-plugins) or plain old [hooks](./hooks) to create a connection.
+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.
 
 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!

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](./root-hook-plugins) are the preferred mechanism for setting root hooks.
+As of v8.0.0, [Root Hook Plugins](/next/features/root-hook-plugins) are the preferred mechanism for setting root hooks.
 
 ## Delayed Root Suite
 
 :::caution
-Delayed root suites are incompatible with [parallel mode](./parallel-mode).
+Delayed root suites are incompatible with [parallel mode](/next/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.