fix/ci: correct cross-instance vNext links, and add a vale rule to advise against them in the future. (#5606)

* rename: add more context to one of the vale rules

* ci: add a vale rule to prevent cross-instance vNext links

* fix: global replace to fix cross-instance links

* revert several links which don't work except across versions

Author: pepopowitz

docs/apis-tools/zeebe-api/grpc.md

@@ -9,7 +9,7 @@ keywords: ["backpressure", "back-pressure", "back pressure"]
 
 [Zeebe](/components/zeebe/zeebe-overview.md) clients use [gRPC](https://grpc.io/) to communicate with the Zeebe cluster. A cross-platform and high-performance remote procedure call (RPC) framework, gRPC offers benefits for microservices architectures, such as bidirectional data streaming and support for high performance use cases. Using this API may be beneficial with Zeebe because it offers advantages for low-latency and high-throughput use cases.
 
-See [Zeebe API RPCs](gateway-service.md) for all available operations. Additionally, review [technical error handling](/docs/apis-tools/zeebe-api/technical-error-handling.md) for a closer look at business logic errors, or [Postman](https://www.postman.com/camundateam/camunda-8-postman/collection/jzgs776/zeebe-api-grpc?action=share&creator=11465105) to experiment with the API.
+See [Zeebe API RPCs](gateway-service.md) for all available operations. Additionally, review [technical error handling](/apis-tools/zeebe-api/technical-error-handling.md) for a closer look at business logic errors, or [Postman](https://www.postman.com/camundateam/camunda-8-postman/collection/jzgs776/zeebe-api-grpc?action=share&creator=11465105) to experiment with the API.
 
 To authorize the Zeebe API (gRPC) in a [Self-Managed](/self-managed/about-self-managed.md) setup,
 see [client authorization](/self-managed/zeebe-deployment/security/client-authorization.md).

docs/components/connectors/protocol/polling.md

@@ -38,20 +38,20 @@ If the HTTP Polling Connector encounters an execution exception while polling, i
 
 ### Authentication
 
-Navigate to the **Authentication** section and select your desired **Authentication type** (e.g., Basic, OAuth). Refer to the [Authentication section of the REST Connector documentation](docs/components/connectors/protocol/rest.md#authentication) for a comprehensive guide.
+Navigate to the **Authentication** section and select your desired **Authentication type** (e.g., Basic, OAuth). Refer to the [Authentication section of the REST Connector documentation](/components/connectors/protocol/rest.md#authentication) for a comprehensive guide.
 
 ### HTTP polling configuration
 
 - **Method**: Choose the HTTP method for your request, e.g., GET, POST, PUT.
 - **URL**: Enter the URL of the targeted HTTP endpoint.
-- **Headers** (Optional): Input required headers as per the external service. Learn more about headers in the [REST Connector headers](docs/components/connectors/protocol/rest.md#http-headers) section.
-- **Query Parameters** (Optional): Add necessary query parameters for the endpoint. More details can be found in the [REST Connector query parameters](docs/components/connectors/protocol/rest.md#query-parameters) section.
+- **Headers** (Optional): Input required headers as per the external service. Learn more about headers in the [REST Connector headers](/components/connectors/protocol/rest.md#http-headers) section.
+- **Query Parameters** (Optional): Add necessary query parameters for the endpoint. More details can be found in the [REST Connector query parameters](/components/connectors/protocol/rest.md#query-parameters) section.
 - **Interval** (Optional): Set the frequency for polling the endpoint in ISO 8601 durations format. The default interval is 50 seconds. Review [how to configure a time duration](../../modeler/bpmn/timer-events/timer-events.md#time-duration) for details.
-- **Connection Timeout**: Define how long (in seconds) the Connector waits before timing out. Further information on this can be found [here](docs/components/connectors/protocol/rest.md#connection-timeout).
+- **Connection Timeout**: Define how long (in seconds) the Connector waits before timing out. Further information on this can be found [here](/components/connectors/protocol/rest.md#connection-timeout).
 
 ### Payload configuration (optional)
 
-In the **Payload** section, you can include a **request body**. Learn more about this [here](docs/components/connectors/protocol/rest.md#request-body).
+In the **Payload** section, you can include a **request body**. Learn more about this [here](/components/connectors/protocol/rest.md#request-body).
 
 ### Condition to proceed
 
@@ -79,7 +79,7 @@ For more information about correlation keys, review the [messages guide](../../.
 
 ## Handling HTTP Connector responses
 
-The response from any HTTP Connector contains the status, headers, and body. Learn more about the response structure [here](docs/components/connectors/protocol/rest.md#response).
+The response from any HTTP Connector contains the status, headers, and body. Learn more about the response structure [here](/components/connectors/protocol/rest.md#response).
 
 To structure and utilize the response:
 
@@ -162,7 +162,7 @@ Whenever the stock level of this particular product goes below 10 units, the BPM
 
 ## Next steps
 
-- Dive deeper into the [REST Connector](docs/components/connectors/protocol/rest.md) to understand its capabilities and configurations.
+- Dive deeper into the [REST Connector](/components/connectors/protocol/rest.md) to understand its capabilities and configurations.
 - Explore [other Connectors available](../out-of-the-box-connectors/available-connectors-overview.md) in Camunda to integrate with various systems and services.
 - Get a comprehensive understanding of how to use Connectors in your BPMN processes [here](../use-connectors/index.md).
 - Learn about the specifics of inbound Connectors and how they can be used [here](../use-connectors/inbound.md).

docs/components/modeler/bpmn/bpmn.md

@@ -25,7 +25,7 @@ Using BPMN in Modeler, you can create more BPMN 2.0 elements like task types and
 
 For example, [service tasks](/components/modeler/bpmn/service-tasks/service-tasks.md) within Camunda 8 require you to set a task type and implement [job workers](/components/concepts/job-workers.md) to perform a particular task in a process.
 
-Review [the BPMN 2.0 coverage documentation](docs/components/modeler/bpmn/bpmn-coverage.md) for a complete list of BPMN elements supported by our modeling tools.
+Review [the BPMN 2.0 coverage documentation](/components/modeler/bpmn/bpmn-coverage.md) for a complete list of BPMN elements supported by our modeling tools.
 
 Additionally, visit [creating readable process models](/components/best-practices/modeling/creating-readable-process-models.md) for general guidelines on modeling with BPMN.
 

docs/components/modeler/bpmn/user-tasks/user-tasks.md

@@ -44,7 +44,7 @@ Note that in SaaS, all user IDs are converted to lowercase by default, as they a
 :::
 
 :::info
-Assignment resources can also be used for set user task restrictions ([SaaS](/components/concepts/access-control/user-task-access-restrictions.md)/[Self-Managed](docs/self-managed/concepts/access-control/user-task-access-restrictions.md)), where users will see only the tasks they have authorization to work on.
+Assignment resources can also be used for set user task restrictions ([SaaS](/components/concepts/access-control/user-task-access-restrictions.md)/[Self-Managed](/self-managed/concepts/access-control/user-task-access-restrictions.md)), where users will see only the tasks they have authorization to work on.
 :::
 
 Typically, the assignee, candidate users, and candidate groups are defined as [static values](/components/concepts/expressions.md#expressions-vs-static-values) (e.g. `some_username`, `some_username, another_username` and

docs/components/modeler/web-modeler/process-landscape-visualization.md

@@ -21,7 +21,7 @@ To open the process landscape view, click **View landscape** from any of the fol
 
 - Project view
 - Folder view
-- [Process application](/docs/components/modeler/web-modeler/process-applications.md) view
+- [Process application](/components/modeler/web-modeler/process-applications.md) view
 
 ![process landscape visualization button](img/process-landscape-view-button.png)
 

docs/reference/announcements-release-notes/860/860-announcements.md

@@ -162,7 +162,7 @@ We are introducing a new base path for both the Operate and Tasklist **web appli
 
 ### Zeebe, Operate, Tasklist, and Optimize released from single repository
 
-To harmonize and simplify, and also to prepare for the [streamlined Orchestration Cluster Architecture](https://camunda.com/blog/2024/04/simplified-deployment-options-accelerated-getting-started-experience/), `Zeebe`, `Operate`, `Tasklist`, and `Optimize` are developed and released from a single repository going forward: https://github.com/camunda/camunda. This prepares for `Zeebe`, `Operate`, `Tasklist`, and a new, Orchestration Cluster level Identity forming the [Orchestration Cluster](/docs/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster) application starting with Camunda 8.8.
+To harmonize and simplify, and also to prepare for the [streamlined Orchestration Cluster Architecture](https://camunda.com/blog/2024/04/simplified-deployment-options-accelerated-getting-started-experience/), `Zeebe`, `Operate`, `Tasklist`, and `Optimize` are developed and released from a single repository going forward: https://github.com/camunda/camunda. This prepares for `Zeebe`, `Operate`, `Tasklist`, and a new, Orchestration Cluster level Identity forming the [Orchestration Cluster](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster) application starting with Camunda 8.8.
 
 This change has the following implications:
 

docs/self-managed/operational-guides/application-configs.md

@@ -335,9 +335,9 @@ zeebe:
       ioThreadCount: "3"
 ```
 
-Next, for each environment variable, we need to find the configuration option in the [Zeebe configuration](docs/self-managed/zeebe-deployment/configuration/broker.md) section of our documentation.
+Next, for each environment variable, we need to find the configuration option in the [Zeebe configuration](/self-managed/zeebe-deployment/configuration/broker.md) section of our documentation.
 
-For `ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME`, we will search this page for anything relating to S3 or bucket name. In this case, the option is in [Zeebe S3 Backup](docs/self-managed/zeebe-deployment/configuration/broker.md#zeebebrokerdatabackups3)
+For `ZEEBE_BROKER_DATA_BACKUP_S3_BUCKETNAME`, we will search this page for anything relating to S3 or bucket name. In this case, the option is in [Zeebe S3 Backup](/self-managed/zeebe-deployment/configuration/broker.md#zeebebrokerdatabackups3)
 with the name `zeebe.broker.data.backup.s3.bucketName`.
 
 In our `config` file, add the `data` section under `zeebe.broker`:

docs/self-managed/operational-guides/update-guide/870-to-880.md

@@ -8,8 +8,8 @@ The following sections explain which adjustments must be made to migrate from Ca
 
 ## Camunda Exporter and harmonized data model
 
-The following Camunda 8.7 to 8.8 update guide covers changes related to the new harmonized data model, and the newly introduced [Camunda Exporter](docs/self-managed/zeebe-deployment/exporters/camunda-exporter.md).
-For additional details about the introduced exporter and related changes, see the [8.8 announcements](docs/reference/announcements-release-notes/880/880-announcements.md).
+The following Camunda 8.7 to 8.8 update guide covers changes related to the new harmonized data model, and the newly introduced [Camunda Exporter](/self-managed/zeebe-deployment/exporters/camunda-exporter.md).
+For additional details about the introduced exporter and related changes, see the [8.8 announcements](/reference/announcements-release-notes/880/880-announcements.md).
 
 :::important
 With the Camunda Exporter introduction, Camunda is compatible with Elasticsearch 8.16+ and no longer supports older Elasticsearch versions. See [supported environments](/reference/supported-environments.md).

docs/self-managed/optimize-deployment/configuration/system-configuration.md

@@ -271,7 +271,7 @@ Settings influencing the process digest feature.
 Settings for automatic cleanup of historic process instances based on their end time.
 
 :::note
-Two types of history cleanup are available for Camunda 8 users at this time - process data cleanup and external variable cleanup. For more information, see [History cleanup](/docs/self-managed/optimize-deployment/configuration/history-cleanup.md).
+Two types of history cleanup are available for Camunda 8 users at this time - process data cleanup and external variable cleanup. For more information, see [History cleanup](/self-managed/optimize-deployment/configuration/history-cleanup.md).
 :::
 
 | YAML path                                                                         | Default value | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

docs/self-managed/reference-architecture/kubernetes.md

@@ -48,7 +48,7 @@ The database is not depicted in the diagram, as we recommend handling it externa
 ### Kubernetes
 
 :::note
-The reference architecture overview describes the difference between the [Orchestration cluster and Web Modeler and Console](/docs/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster-vs-web-modeler-and-console), and provides additional information on application communication.
+The reference architecture overview describes the difference between the [Orchestration cluster and Web Modeler and Console](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster-vs-web-modeler-and-console), and provides additional information on application communication.
 :::
 
 A [multi-namespace deployment](/self-managed/setup/guides/multi-namespace-deployment.md) is recommended. For more information, see the [components](#components) section.

styles/camunda/all/markdownLinksDontCrossVersions.yml

@@ -0,0 +1,9 @@
+extends: substitution
+message: "Exclude the `docs/` prefix in markdown links, unless you intend to link only to vNext. Consider using `%s` instead of `%s`."
+level: warning
+nonword: true
+scope: raw
+swap:
+  # Captures any links that start with `docs/` (or `/docs/`) and include a .md extension.
+  #   These are links that would cross versions into vNext.
+  - "(\\[[^\\]]*\\]\\()\\/?docs(\\/[^\\)]*\\.md[^\\)]*\\))": "$1$2"

styles/camunda/all/hrefProduction.yml renamed to styles/camunda/all/markdownLinksDontExitToProduction.yml

@@ -67,7 +67,7 @@ The OAuth service rate limits about one request per second for all clients with
 All token requests count toward the rate limit, whether they are successful or not. If any client is running with an expired or invalid API key, that client will continually make token requests. That client will therefore exceed the rate limit for that IP address, and may block valid token requests from completing.
 :::
 
-The officially offered [client libraries](/docs/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
+The officially offered [client libraries](/apis-tools/working-with-apis-tools.md) (as well as the Node.js and Spring clients) have already integrated with the auth routine, handle obtaining and refreshing an access token, and make use of a local cache.
 
 If too many token requests are executed from the same source IP address in a short time, all token requests from that source IP address are blocked for a certain time. Since the access tokens have a 24-hour validity period, they must be cached on the client side, reused while still valid, and refreshed via a new token request once the validity period has expired.
 

versioned_docs/version-8.4/apis-tools/administration-api/authentication.md

@@ -23,7 +23,7 @@ Make sure you keep the generated client credentials in a safe place. The **Clien
 ## Getting started
 
 - A detailed API description can be found [here](https://console.cloud.camunda.io/customer-api/openapi/docs/#/) via Swagger. With a valid access token, this offers an interactive API experience against your Camunda 8 cluster.
-- You need authentication to access the API endpoints. Find more information [here](/docs/apis-tools/administration-api/authentication.md).
+- You need authentication to access the API endpoints. Find more information [here](/apis-tools/administration-api/authentication.md).
 
 ## Set up authentication
 

versioned_docs/version-8.4/apis-tools/administration-api/tutorial.md

@@ -9,7 +9,7 @@ In this tutorial, we'll step through examples to highlight the capabilities of t
 
 ## Getting started
 
-- You need authentication to access the API endpoints. Find more information [here](/docs/apis-tools/operate-api/overview.md#authentication).
+- You need authentication to access the API endpoints. Find more information [here](/apis-tools/operate-api/overview.md#authentication).
 - We will use the `bpmn-js` library to render the diagram and add overlays. Visit the documentation on [embedding the pre-packaged viewer](https://bpmn.io/toolkit/bpmn-js/walkthrough/#viewer-pre-packaged) for more details.
 
 ## Set up the demo project

versioned_docs/version-8.4/apis-tools/operate-api/tutorial.md

@@ -10,7 +10,7 @@ keywords: ["process automation tools"]
 This section contains product manual content for each component in Camunda 8, including conceptual content. Together, these components comprise the Camunda 8 SaaS experience.
 
 - [Concepts](concepts/what-is-camunda-8.md) - Learn more about a variety of Camunda 8 topics with this conceptual documentation on clusters, processes, job workers, workflow patterns, and more.
-- [Console](console/introduction-to-console.md) - With this management application for the included products, create and delete clusters, manage API clients and alerts, and more. As of version 8.4, Console is only available for Camunda 8 SaaS. For Self-Managed content, visit our [Self-Managed documentation](/docs/self-managed/about-self-managed.md).
+- [Console](console/introduction-to-console.md) - With this management application for the included products, create and delete clusters, manage API clients and alerts, and more. As of version 8.4, Console is only available for Camunda 8 SaaS. For Self-Managed content, visit our [Self-Managed documentation](/self-managed/about-self-managed.md).
 - [Modeler](modeler/about-modeler.md) - Design and implement diagrams using Camunda's modeling tools, including Web Modeler and Desktop Modeler.
 - [Connectors](connectors/introduction.md) - Integrate with external systems using these reusable building blocks.
 - [Zeebe](zeebe/zeebe-overview.md) - Define processes graphically in BPMN 2.0, choose any gRPC-supported programming language to implement your workers, build processes that react to events from Apache Kafka, and more using this workflow engine powering Camunda 8.

versioned_docs/version-8.4/components/components-overview.md

@@ -56,7 +56,7 @@ If you require more retained backups or more frequent backups, contact your Cust
 
 The backup operations can be performed programmatically using the Administration API.
 This provides the flexibility to seamlessly integrate backup-related tasks with your existing systems and automation workflows.
-For detailed information on using the API, refer to the [Administration API reference](/docs/apis-tools/administration-api/administration-api-reference.md).
+For detailed information on using the API, refer to the [Administration API reference](/apis-tools/administration-api/administration-api-reference.md).
 
 ## Restore
 

versioned_docs/version-8.4/components/concepts/backups.md

@@ -54,7 +54,7 @@ The way this type of cluster works varies depending on if you are using it in th
 
 ### Development clusters in the Enterprise plan
 
-Enterprise plan users can purchase development clusters as part of their Enterprise subscription agreement. Deployment and execution of models (process instances, decision instances, and task users) are included at no extra cost for this type of cluster. Additionally, this type of cluster in the Enterprise plan follows the [standard data retention policy](/docs/components/concepts/data-retention.md) and does not auto-pause when not in use.
+Enterprise plan users can purchase development clusters as part of their Enterprise subscription agreement. Deployment and execution of models (process instances, decision instances, and task users) are included at no extra cost for this type of cluster. Additionally, this type of cluster in the Enterprise plan follows the [standard data retention policy](/components/concepts/data-retention.md) and does not auto-pause when not in use.
 
 Please [contact us](/reference/contact.md) if you are an existing customer and would like to purchase a development cluster.