Fix links

Author: marcphilipp

documentation/modules/ROOT/pages/advanced-topics/engines.adoc

@@ -4,9 +4,9 @@ A `TestEngine` facilitates _discovery_ and _execution_ of tests for a particular
 programming model.
 
 For example, JUnit provides a `TestEngine` that discovers and executes tests written using
-the JUnit Jupiter programming model (see <<writing-tests>> and <<extensions>>).
+the JUnit Jupiter programming model (see xref:writing-tests/intro.adoc[] and xref:extensions/overview.adoc[]).
 
-[[test-engines-junit]]
+[[junit]]
 == JUnit Test Engines
 
 JUnit provides three `TestEngine` implementations.
@@ -17,7 +17,7 @@ JUnit provides three `TestEngine` implementations.
 * `{junit-platform-suite-engine}`: Executes declarative suites of tests with the JUnit
   Platform launcher infrastructure.
 
-[[test-engines-custom]]
+[[custom]]
 == Custom Test Engines
 
 You can contribute your own custom `{TestEngine}` by implementing the interfaces in the
@@ -45,7 +45,7 @@ annotation. For example, the `@Test` and `@TestFactory` annotations in JUnit Jup
 meta-annotated with `@Testable`. Consult the Javadoc for `{Testable}` for further details.
 
 If your custom `TestEngine` needs to be configured, consider allowing users to supply
-configuration via <<running-tests-config-params,configuration parameters>>. Please note,
+configuration via xref:running-tests/configuration-parameters.adoc[configuration parameters]. Please note,
 however, that you are strongly encouraged to use a unique prefix for all configuration
 parameters supported by your test engine. Doing so will ensure that there are no conflicts
 between the names of your configuration parameters and those from other test engines. In
@@ -57,7 +57,7 @@ parameters. Furthermore, as with the warning above regarding the `junit-` prefix
 configuration parameters.
 
 Although there is currently no official guide on how to implement a custom `TestEngine`,
-you can consult the implementation of <<test-engines-junit>> or the implementation of
+you can consult the implementation of <<junit>> or the implementation of
 third-party test engines listed in the
 https://github.com/junit-team/junit-framework/wiki/Third-party-Extensions#junit-platform-test-engines[JUnit wiki].
 You will also find various tutorials and blogs on the Internet that demonstrate how to
@@ -68,7 +68,7 @@ NOTE: `{HierarchicalTestEngine}` is a convenient abstract base implementation of
 provide the logic for test discovery. It implements execution of `TestDescriptors` that
 implement the `Node` interface, including support for parallel execution.
 
-[[test-engines-registration]]
+[[registration]]
 == Registering a TestEngine
 
 `TestEngine` registration is supported via Java's `{ServiceLoader}` mechanism.
@@ -78,14 +78,14 @@ For example, the `junit-jupiter-engine` module registers its
 `org.junit.platform.engine.TestEngine` within the `/META-INF/services` folder in the
 `junit-jupiter-engine` JAR.
 
-[[test-engines-requirements]]
+[[requirements]]
 == Requirements
 
 NOTE: The words "must", "must not", "required", "shall", "shall not", "should", "should
 not", "recommended",  "may", and "optional" in this section are to be interpreted as
 described in https://www.ietf.org/rfc/rfc2119.txt[RFC 2119.]
 
-[[test-engines-requirements-mandatory]]
+[[requirements-mandatory]]
 === Mandatory requirements
 
 For interoperability with build tools and IDEs, `TestEngine` implementations must adhere
@@ -106,7 +106,7 @@ to the following requirements:
   after their children. If a node is reported as skipped, there _must not_ be any events
   reported for its descendants.
 
-[[test-engines-requirements-enhanced-compatibility]]
+[[requirements-enhanced-compatibility]]
 === Enhanced compatibility
 
 Adhering to the following requirements is optional but recommended for enhanced
@@ -119,20 +119,20 @@ compatibility with build tools and IDEs:
 * When resolving `UniqueIdSelectors`, a `TestEngine` _should_ only return `TestDescriptor`
   instances with matching unique IDs including their ancestors but _may_ return additional
   siblings or other nodes that are required for the execution of the selected tests.
-* `TestEngines` _should_ support <<running-tests-tags, tagging>> tests and containers so
+* `TestEngines` _should_ support xref:running-tests/tags.adoc[tagging] tests and containers so
   that tag filters can be applied when discovering tests.
-* [[test-engines-requirements-cancellation]] A `TestEngine` _should_ cancel its execution
+* [[requirements-cancellation]] A `TestEngine` _should_ cancel its execution
   when the `{CancellationToken}` it is passed as part of the `ExecutionRequest` indicates
   that cancellation has been requested. In this case, it _should_ report any remaining
   `TestDescriptors` as skipped but not report any events for their descendants. It _may_
   report already started `TestDescriptors` as aborted in case they have not been executed
   completely. If a `TestEngine` supports cancellation, it should clean up any resources
   that it has created just like if execution had finished regularly.
 
-[[test-engines-discovery-issues]]
+[[discovery-issues]]
 == Reporting Discovery Issues
 
-Test engines should report <<running-tests-discovery-issues, discovery issues>> if they
+Test engines should report xref:running-tests/discovery-issues.adoc[discovery issues] if they
 encounter any problems or potential misconfigurations during test discovery. This is
 especially important if the issue could lead to tests not being executed at all or only
 partially.
@@ -143,7 +143,7 @@ In order to report a `{DiscoveryIssue}`, a test engine should call the
 listener around, the `{DiscoveryIssueReporter}` interface should be used. It also provides
 a way to create a `Condition` that reports a discovery issue if its check fails and may
 be used as a `Predicate` or `Consumer`. Please refer to the implementations of the
-<<test-engines-junit, test engines provided by JUnit>> for examples.
+<<junit, test engines provided by JUnit>> for examples.
 
-Moreover, <<testkit-engine-discovery, Engine Test Kit>> provides a way to write tests for
+Moreover, xref:advanced-topics/testkit.adoc#engine-discovery[Engine Test Kit] provides a way to write tests for
 reported discovery issues.

documentation/modules/ROOT/pages/advanced-topics/junit-platform-reporting.adoc

@@ -2,19 +2,19 @@
 
 The `junit-platform-reporting` artifact contains `{TestExecutionListener}` implementations
 that generate XML test reports in two flavors:
-<<junit-platform-reporting-open-test-reporting, Open Test Reporting>> and
-<<junit-platform-reporting-legacy-xml, legacy>>.
+<<open-test-reporting, Open Test Reporting>> and
+<<legacy-xml, legacy>>.
 
 NOTE: The module also contains other `TestExecutionListener` implementations that can be
-used to build custom reporting. See <<running-tests-listeners>> for details.
+used to build custom reporting. See xref:running-tests/using-listeners-and-interceptors.adoc[] for details.
 
-[[junit-platform-reporting-output-directory]]
+[[output-directory]]
 == Output Directory
 
 The JUnit Platform provides an `{OutputDirectoryCreator}` via `{EngineDiscoveryRequest}`
-and `{TestPlan}` to registered <<test-engines, test engines>> and
-<<running-tests-listeners, listeners>>, respectively. Its root directory can be configured
-via the following <<running-tests-config-params, configuration parameter>>:
+and `{TestPlan}` to registered xref:advanced-topics/engines.adoc[test engines] and
+xref:running-tests/using-listeners-and-interceptors.adoc[listeners], respectively. Its root directory can be configured
+via the following xref:running-tests/configuration-parameters.adoc[configuration parameter]:
 
 `junit.platform.reporting.output.dir=<path>`::
   Configure the output directory for reporting. By default, `build` is used if a Gradle
@@ -27,15 +27,15 @@ directories like `reports/junit-8803697269315188212`. This can be useful when us
 Gradle's or Maven's parallel execution capabilities which create multiple JVM forks
 that run concurrently.
 
-[[junit-platform-reporting-open-test-reporting]]
+[[open-test-reporting]]
 == Open Test Reporting
 
 `{OpenTestReportGeneratingListener}` writes an XML report for the entire execution in the
 event-based format specified by {OpenTestReporting} which supports all features of the
 JUnit Platform such as hierarchical test structures, display names, tags, etc.
 
 The listener is auto-registered and can be configured via the following
-<<running-tests-config-params, configuration parameters>>:
+xref:running-tests/configuration-parameters.adoc[configuration parameters]:
 
 `junit.platform.reporting.open.xml.enabled=true|false`::
   Enable/disable writing the report; defaults to `false`.
@@ -47,11 +47,11 @@ The listener is auto-registered and can be configured via the following
   connection is automatically closed when the test execution completes.
 
 If enabled, the listener creates an XML report file named `open-test-report.xml` in the
-configured <<junit-platform-reporting-output-directory, output directory>>, unless the
+configured <<output-directory, output directory>>, unless the
 `junit.platform.reporting.open.xml.socket` configuration parameter is set, in which case the
 events are sent to the specified socket instead.
 
-If <<running-tests-capturing-output, output capturing>> is enabled, the captured output
+If xref:running-tests/capturing-standard-output-error.adoc[output capturing] is enabled, the captured output
 written to `System.out` and `System.err` will be included in the report as well.
 
 TIP: The {OpenTestReportingCliTool} can be used to convert from the event-based format to
@@ -142,7 +142,7 @@ XML reports as follows:
 
 === Console Launcher
 
-When using the <<running-tests-console-launcher>>, you can enable Open Test Reporting
+When using the xref:running-tests/console-launcher.adoc[], you can enable Open Test Reporting
 output by setting the configuration parameters via `--config`:
 
 [source,console,subs=attributes+]
@@ -161,12 +161,12 @@ $ java -jar junit-platform-console-standalone-{version}.jar <OPTIONS> \
   --config-resource=configuration.properties
 ----
 
-[[junit-platform-reporting-legacy-xml]]
+[[legacy-xml]]
 == Legacy XML format
 
 `{LegacyXmlReportGeneratingListener}` generates a separate XML report for each root in the
 `{TestPlan}`. Note that the generated XML format is compatible with the de facto standard
 for JUnit 4 based test reports that was made popular by the Ant build system.
 
-The `LegacyXmlReportGeneratingListener` is used by the <<running-tests-console-launcher>>
+The `LegacyXmlReportGeneratingListener` is used by the xref:running-tests/console-launcher.adoc[]
 as well.

documentation/modules/ROOT/pages/advanced-topics/junit-platform-suite-engine.adoc

@@ -1,18 +1,18 @@
 = JUnit Platform Suite Engine
 
 The Suite Engine supports the declarative selection and execution of tests from _any_ test
-engine on the JUnit Platform using the <<launcher-api>>.
+engine on the JUnit Platform using the xref:advanced-topics/launcher-api.adoc[].
 
 image::junit-platform-suite-engine-diagram.svg[role=text-center]
 
-[[junit-platform-suite-engine-setup]]
+[[setup]]
 == Setup
 
 In addition to the `junit-platform-suite-api` and `junit-platform-suite-engine` artifacts,
 you need _at least one_ other test engine and its dependencies on the classpath. See
-<<dependency-metadata>> for details regarding group IDs, artifact IDs, and versions.
+xref:appendix.adoc#dependency-metadata[Dependency Metadata] for details regarding group IDs, artifact IDs, and versions.
 
-[[junit-platform-suite-engine-setup-required-dependencies]]
+[[setup-required-dependencies]]
 === Required Dependencies
 
 * `junit-platform-suite-api` in _test_ scope: artifact containing annotations needed to
@@ -24,15 +24,15 @@ NOTE: Both of the required dependencies are aggregated in the `junit-platform-su
 artifact which can be declared in _test_ scope instead of declaring explicit dependencies
 on `junit-platform-suite-api` and `junit-platform-suite-engine`.
 
-[[junit-platform-suite-engine-setup-transitive-dependencies]]
+[[setup-transitive-dependencies]]
 === Transitive Dependencies
 
 * `junit-platform-launcher` in _test_ scope
 * `junit-platform-engine` in _test_ scope
 * `junit-platform-commons` in _test_ scope
 * `opentest4j` in _test_ scope
 
-[[junit-platform-suite-engine-example]]
+[[example]]
 == @Suite Example
 
 Annotate a class with `@Suite` to have it marked as a test suite on the JUnit Platform. As
@@ -60,7 +60,7 @@ suite, respectively.
 include::example$java/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]
 ----
 
-[[junit-platform-suite-engine-duplicate-test-execution]]
+[[duplicate-test-execution]]
 == Duplicate Test Execution
 
 Depending on the declared selectors, different suites may contain the same tests,
@@ -75,5 +75,5 @@ include only the `junit-platform-suite` engine, or use a custom naming pattern.
 example, name all suites `*Suite` and all tests `*Test`, and configure your build tool to
 include only the former.
 
-Alternatively, consider <<running-tests-tags, using tags>> to select specific groups of
+Alternatively, consider xref:running-tests/tags.adoc[using tags] to select specific groups of
 tests.