Fix improperly formatted internal deep links; prevent them from happe…

…ning again. (#4902)

* feat: new vale rule for improperly formatted deep-links

* fix: correct markdown deep links

* elevate level

* escape links in vale/reviewdog comments

docs/apis-tools/frontend-development/01-task-applications/01-introduction-to-task-applications.md

@@ -13,7 +13,7 @@ Task applications are the interface between humans and Camunda processes to orch
 
 ## What are task applications?
 
-Task applications are end-user applications that allow humans to perform work orchestrated with a process. A [user task](/components/modeler/bpmn/user-tasks/user-tasks.md/#user-task-forms) (for [human task orchestration](/guides/getting-started-orchestrate-human-tasks.md)) represents a single **work item** to be performed by an individual or a group. The jobs of a task application include:
+Task applications are end-user applications that allow humans to perform work orchestrated with a process. A [user task](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms) (for [human task orchestration](/guides/getting-started-orchestrate-human-tasks.md)) represents a single **work item** to be performed by an individual or a group. The jobs of a task application include:
 
 - Listing available tasks and allowing users to select a task to work on.
 - Providing filter and search options for users so they can more easily find the right next task to work on.
@@ -59,9 +59,9 @@ Task details are shown when a task is selected from the queue. A [form](/guides/
 :::tip
 Typically, a task application utilizes forms to capture information from the user, to make a decision, to collect the results from a real-world task, or to provide task instructions to the user.
 
-However, a [user task](/components/modeler/bpmn/user-tasks/user-tasks.md/#user-task-forms) is not limited to forms. A user task could also represent navigating to an external desktop or web application, where a task is to be performed, such as updating a record in a CRM. You can even use them to track physical work or actions using sensors, IoT devices, or any interface that can talk to the web, by using the [APIs](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) or registering a [job worker](/components/concepts/job-workers.md) to the job type `io.camunda.zeebe:userTask` (compatible with [job worker-based user tasks](/components/modeler/bpmn/user-tasks/user-tasks.md) only).
+However, a [user task](/components/modeler/bpmn/user-tasks/user-tasks.md#user-task-forms) is not limited to forms. A user task could also represent navigating to an external desktop or web application, where a task is to be performed, such as updating a record in a CRM. You can even use them to track physical work or actions using sensors, IoT devices, or any interface that can talk to the web, by using the [APIs](/apis-tools/tasklist-api-rest/tasklist-api-rest-overview.md) or registering a [job worker](/components/concepts/job-workers.md) to the job type `io.camunda.zeebe:userTask` (compatible with [job worker-based user tasks](/components/modeler/bpmn/user-tasks/user-tasks.md) only).
 
-For these cases, utilize the flexible [custom form key](/components/modeler/web-modeler/advanced-modeling/form-linking.md/#custom-form-key).
+For these cases, utilize the flexible [custom form key](/components/modeler/web-modeler/advanced-modeling/form-linking.md#custom-form-key).
 :::
 
 On the top of the form, a header shows the title of the task to work on, and the current assignee. Depending on the status of the assignment, a button allows you to assign the task to yourself or release it to the queue.

docs/components/concepts/execution-listeners.md

@@ -53,7 +53,7 @@ Execution listeners are processed by [job workers](/components/concepts/job-work
 See [open a job worker](/apis-tools/java-client-examples/job-worker-open.md) for an example of how to create a job worker and handler that can also process execution listener jobs.
 
 :::note
-[Throwing a BPMN error](/components/best-practices/development/dealing-with-problems-and-exceptions.md/#throwing-and-handling-bpmn-errors) for an execution listener's job is not supported.
+[Throwing a BPMN error](/components/best-practices/development/dealing-with-problems-and-exceptions.md#throwing-and-handling-bpmn-errors) for an execution listener's job is not supported.
 :::
 
 ## Variables in an execution listener

docs/components/concepts/job-workers.md

@@ -92,8 +92,8 @@ Job workers can provide a **job result** for [user task listeners](components/co
 
 Job results are used to define:
 
-1. **Corrections**: Updates to specific user task attributes, such as assignee, due date, follow-up date, candidate users, candidate groups, and priority, before the task transition is finalized. For more details, see [correcting user task data](components/concepts/user-task-listeners.md/#correcting-user-task-data).
-2. **Denial**: Indicates that the lifecycle transition should be explicitly denied. Denying the task lifecycle transition rolls back the user task to the previous state, and discards any corrections made by previous listeners. For more details, see [denying the operation](components/concepts/user-task-listeners.md/#denying-the-operation).
+1. **Corrections**: Updates to specific user task attributes, such as assignee, due date, follow-up date, candidate users, candidate groups, and priority, before the task transition is finalized. For more details, see [correcting user task data](components/concepts/user-task-listeners.md#correcting-user-task-data).
+2. **Denial**: Indicates that the lifecycle transition should be explicitly denied. Denying the task lifecycle transition rolls back the user task to the previous state, and discards any corrections made by previous listeners. For more details, see [denying the operation](components/concepts/user-task-listeners.md#denying-the-operation).
 
 Below is an example of using job result:
 

docs/components/console/manage-clusters/settings.md

@@ -24,7 +24,7 @@ You can enable resource-based authorization on a per-cluster basis to control th
 - Disable this setting if you do not want to use resource-based authorization in the cluster. You can still configure resource authorizations, but they are only applied to cluster users when you enable this setting.
 
 :::tip
-For more information on resource-based authorization, see [resource authorizations](/components/concepts/resource-authorizations.md) and [resource-based authorization](/components/console/manage-organization/manage-users.md/#resource-based-authorizations).
+For more information on resource-based authorization, see [resource authorizations](/components/concepts/resource-authorizations.md) and [resource-based authorization](/components/console/manage-organization/manage-users.md#resource-based-authorizations).
 :::
 
 ## Automatic cluster updates

docs/components/modeler/web-modeler/collaborate-with-modes.md

@@ -31,4 +31,4 @@ When a process template is selected, the default mode is **Implement**.
   ![read only properties](img/read-only-properties.png)
 - **Viewers** can access only the **Design** mode with read-only permission,
 
-Read more about the [different roles and how to assign them](components/modeler/web-modeler/collaboration.md/#access-rights-and-permissions).
+Read more about the [different roles and how to assign them](components/modeler/web-modeler/collaboration.md#access-rights-and-permissions).

docs/components/modeler/web-modeler/deploy-process-application.md

@@ -39,7 +39,7 @@ Once validation is complete, deploy your process application to cluster stages i
 
 All BPMN, DMN, and form files contained in the process application folder are deployed as a single bundle.
 
-In Self-Managed, you can deploy your diagram to the cluster defined in your Web Modeler [configuration](/self-managed/modeler/web-modeler/configuration/configuration.md#clusters). You should have the `Zeebe` [role](/self-managed/identity/user-guide/roles/add-assign-role.md/#add-a-role) assigned in Identity to be authorized to deploy.
+In Self-Managed, you can deploy your diagram to the cluster defined in your Web Modeler [configuration](/self-managed/modeler/web-modeler/configuration/configuration.md#clusters). You should have the `Zeebe` [role](/self-managed/identity/user-guide/roles/add-assign-role.md#add-a-role) assigned in Identity to be authorized to deploy.
 
 :::note
 If any resource fails to deploy, the whole deployment [fails](#deployment-errors) and the cluster state remains unchanged. This safely ensures that a process application cannot be deployed incompletely or in an inconsistent state.

docs/components/modeler/web-modeler/play-your-process.md

@@ -231,7 +231,7 @@ After selecting the **Play** tab in Self-Managed, you are prompted to select fro
 - The environment variables `CAMUNDA_CUSTOM_CERT_CHAIN_PATH`, `CAMUNDA_CUSTOM_PRIVATE_KEY_PATH`, `CAMUNDA_CUSTOM_ROOT_CERT_PATH`, and `CAMUNDA_CUSTOM_ROOT_CERT_STRING` can be set in Docker or Helm chart setups. However, these configurations have not been tested with Play's behavior, and therefore are not supported when used with Play.
 - Play cannot check the presence of Connector secrets in Self-Managed setups.
   If a secret is missing, Play will show an incident at runtime.
-  Learn more about [configuring Connector secrets](/self-managed/connectors-deployment/connectors-configuration.md/#secrets).
+  Learn more about [configuring Connector secrets](/self-managed/connectors-deployment/connectors-configuration.md#secrets).
 
 ## Play Usage and Billing Considerations
 

docs/components/modeler/web-modeler/run-or-publish-your-process.md

@@ -37,7 +37,7 @@ To deploy, click **Deploy** in the upper right corner of the modeling screen:
 
 ![The deploy dialog of a BPMN diagram](img/web-modeler-deploy.png)
 
-In Self-Managed, you can deploy your diagram to the cluster defined in your Web Modeler [configuration](/self-managed/modeler/web-modeler/configuration/configuration.md#clusters). You should have the `Zeebe` [role](/self-managed/identity/user-guide/roles/add-assign-role.md/#add-a-role) assigned in Identity to be authorized to deploy.
+In Self-Managed, you can deploy your diagram to the cluster defined in your Web Modeler [configuration](/self-managed/modeler/web-modeler/configuration/configuration.md#clusters). You should have the `Zeebe` [role](/self-managed/identity/user-guide/roles/add-assign-role.md#add-a-role) assigned in Identity to be authorized to deploy.
 
 ### Before deploying a process
 

docs/reference/release-notes/850.md

@@ -272,7 +272,7 @@ The shared processes require Tasklist authorization to be started, in contrast t
 
 <!-- https://github.com/camunda/product-hub/issues/2026 -->
 
-Users now have the option to [automatically select](/components/tasklist/userguide/using-tasklist.md/#auto-select-first-available-task) the next available task in Tasklist to speed up task workflows.
+Users now have the option to [automatically select](/components/tasklist/userguide/using-tasklist.md#auto-select-first-available-task) the next available task in Tasklist to speed up task workflows.
 
 ### Hot backups: Azure Cloud Storage support <span class="badge badge--long" title="This feature affects Self-Managed">Self-Managed</span>
 

docs/self-managed/concepts/access-control/user-task-access-restrictions.md

@@ -15,7 +15,7 @@ User task access restrictions allow you to control the level of access a [user](
 
 ### User task access restrictions
 
-[User task access restrictions](self-managed/tasklist-deployment/tasklist-authentication.md/#user-restrictions) are used in Tasklist to control task access for a
+[User task access restrictions](self-managed/tasklist-deployment/tasklist-authentication.md#user-restrictions) are used in Tasklist to control task access for a
 user or [group](/self-managed/identity/user-guide/groups/create-group.md). The restrictions are
 related to the candidate users or groups set up on user task definitions.
 

docs/self-managed/setup/deploy/amazon/aws-ec2.md

@@ -6,7 +6,7 @@ description: "Learn how to install Camunda 8 on AWS EC2 instances."
 
 This guide provides a detailed walkthrough for installing the Camunda 8 single JAR on AWS EC2 instances. It focuses on managed services by AWS and their cloud offering. Finally, you will verify that the connection to your Self-Managed Camunda 8 environment is working.
 
-This guide focuses on setting up the [orchestration cluster](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster-vs-web-modeler-and-console) for Camunda 8. The Web Modeler and Console are not covered in this manual deployment approach. These components are supported on Kubernetes and should be [deployed using Kubernetes](/self-managed/setup/install.md/#install-web-modeler).
+This guide focuses on setting up the [orchestration cluster](/self-managed/reference-architecture/reference-architecture.md#orchestration-cluster-vs-web-modeler-and-console) for Camunda 8. The Web Modeler and Console are not covered in this manual deployment approach. These components are supported on Kubernetes and should be [deployed using Kubernetes](/self-managed/setup/install.md#install-web-modeler).
 
 :::note Using other Cloud providers
 This guide is built around the available tools and services that AWS offers, but is not limited to AWS. The scripts and ideas included can be adjusted for any other cloud provider and use case.

docs/self-managed/setup/deploy/local/c8run.md

@@ -87,7 +87,7 @@ A success notification displays when complete. [Start a new process instance](/c
 
 ### Use built-in and custom Connectors
 
-Desktop Modeler [automatically fetches](/components/modeler/desktop-modeler/use-connectors.md/#automatic-connector-template-fetching) templates for pre-built Connectors. [Custom Connectors](/components/connectors/custom-built-connectors/connector-sdk.md) can also be added to your Camunda 8 Run distribution.
+Desktop Modeler [automatically fetches](/components/modeler/desktop-modeler/use-connectors.md#automatic-connector-template-fetching) templates for pre-built Connectors. [Custom Connectors](/components/connectors/custom-built-connectors/connector-sdk.md) can also be added to your Camunda 8 Run distribution.
 
 To add a custom Connector:
 

docs/self-managed/setup/deploy/local/manual.md

@@ -233,7 +233,7 @@ A local setup of Identity in Camunda 8 is not yet supported out-of-the-box, use
 
 ## Run Optimize
 
-The installation of Optimize is described in [Optimize Setup]($optimize$/self-managed/optimize-deployment/install-and-start). A local setup in Camunda 8 is not yet supported out-of-the-box, use [Docker](/self-managed/setup/deploy/other/docker.md/#optimize) instead.
+The installation of Optimize is described in [Optimize Setup]($optimize$/self-managed/optimize-deployment/install-and-start). A local setup in Camunda 8 is not yet supported out-of-the-box, use [Docker](/self-managed/setup/deploy/other/docker.md#optimize) instead.
 
 ## Run Web Modeler
 

docs/self-managed/setup/guides/connect-to-an-oidc-provider.md

@@ -19,7 +19,7 @@ In this guide, we step through the configuration required to connect Camunda to
   - Client ID
   - Client secrets
   - Audience
-- A [claim name and value](/self-managed/identity/deployment/configuration-variables.md/#oidc-configuration) to use for initial access.
+- A [claim name and value](/self-managed/identity/deployment/configuration-variables.md#oidc-configuration) to use for initial access.
 
 :::note
 The steps below are a general approach for the Camunda components; it is important you reference the [component-specific

docs/self-managed/zeebe-deployment/configuration/broker.md

@@ -870,7 +870,7 @@ as well.
 :::
 
 :::note
-If you are using a standalone gateway, refer to the [gateway configuration guide](./gateway.md/#zeebegatewaymultitenancy).
+If you are using a standalone gateway, refer to the [gateway configuration guide](./gateway.md#zeebegatewaymultitenancy).
 :::
 
 | Field   | Description                                                                                                                                                  | Example value |

docs/self-managed/zeebe-deployment/configuration/gateway.md

@@ -497,7 +497,7 @@ as well.
 :::
 
 :::note
-If you are using an embedded gateway, refer to the [broker configuration guide](./broker.md/#multitenancy-configuration).
+If you are using an embedded gateway, refer to the [broker configuration guide](./broker.md#multitenancy-configuration).
 :::
 
 | Field   | Description                                                                                                                                     | Example value |

styles/camunda/all/deepLinksAreFormattedCorrectly.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: "Improper link format for deep-links. Exclude the slash (`/`) before the hash (`#`): `%s`"
+level: error
+nonword: true
+scope: raw
+swap:
+  # Captures any markdown link that includes a slash between the extension and hash.
+  "(\\[[^\\]]*\\]\\([^\\)]*(\\.md|\\.mdx))\\/#([^\\)]*\\))": "$1#$3"

styles/camunda/all/hrefProduction.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Improper link format: '%s'. Please use relative URLs."
+message: "Improper link format: `%s`. Please use relative URLs."
 level: warning
 nonword: true
 scope: raw

styles/camunda/docsInstance/hrefDocsToDocs.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Improper link format: '%s'. Please specify the file extension."
+message: "Improper link format: `%s`. Please specify the file extension."
 level: warning
 nonword: true
 scope: raw

styles/camunda/docsInstance/hrefDocsToOptimize.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Improper link format: '%s'. Please use the `$optimize$` token when crossing doc instances."
+message: "Improper link format: `%s`. Please use the `$optimize$` token when crossing doc instances."
 level: warning
 nonword: true
 scope: raw

styles/camunda/optimizeInstance/hrefOptimizeToDocs.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Improper link format: '%s'. Please use the `$docs$` token when crossing doc instances."
+message: "Improper link format: `%s`. Please use the `$docs$` token when crossing doc instances."
 level: warning
 nonword: true
 scope: raw

styles/camunda/optimizeInstance/hrefOptimizeToOptimize.yml

@@ -1,5 +1,5 @@
 extends: existence
-message: "Improper link format: '%s'. Please specify the file extension."
+message: "Improper link format: `%s`. Please specify the file extension."
 level: warning
 nonword: true
 scope: raw

versioned_docs/version-8.3/components/console/manage-clusters/settings.md

@@ -24,7 +24,7 @@ You can enable resource-based authorization on a per-cluster basis to control th
 - Disable this setting if you do not want to use resource-based authorization in the cluster. You can still configure resource authorizations, but they are only applied to cluster users when you enable this setting.
 
 :::tip
-For more information on resource-based authorization, see [resource authorizations](/components/concepts/resource-authorizations.md) and [resource-based authorization](/components/console/manage-organization/manage-users.md/#resource-based-authorizations).
+For more information on resource-based authorization, see [resource authorizations](/components/concepts/resource-authorizations.md) and [resource-based authorization](/components/console/manage-organization/manage-users.md#resource-based-authorizations).
 :::
 
 ## Automatic cluster updates

versioned_docs/version-8.3/self-managed/react-components/components.md

@@ -7,7 +7,7 @@
 - Connectors
 - Optimize
 - Identity
-- Web Modeler [<span class="badge badge--enterprise-only">Enterprise only</span>](/reference/licenses.md/#web-modeler)
+- Web Modeler [<span class="badge badge--enterprise-only">Enterprise only</span>](/reference/licenses.md#web-modeler)
 
 All components except Web Modeler and Console are single Java applications. Depending on your needs, you might not need all of the above components to successfully use Camunda 8.
 

versioned_docs/version-8.3/self-managed/zeebe-deployment/configuration/broker.md

@@ -584,7 +584,7 @@ as well.
 :::
 
 :::note
-If you are using a standalone gateway, refer to the [gateway configuration guide](./gateway.md/#zeebegatewaymultitenancy).
+If you are using a standalone gateway, refer to the [gateway configuration guide](./gateway.md#zeebegatewaymultitenancy).
 :::
 
 | Field   | Description                                                                                                                                                  | Example value |

versioned_docs/version-8.3/self-managed/zeebe-deployment/configuration/gateway.md

@@ -335,7 +335,7 @@ To use multi-tenancy, you must set [`authentication.mode`](#zeebegatewayclusters
 :::
 
 :::note
-If you are using an embedded gateway, refer to the [broker configuration guide](./broker.md/#multitenancy-configuration).
+If you are using an embedded gateway, refer to the [broker configuration guide](./broker.md#multitenancy-configuration).
 :::
 
 | Field   | Description                                                                                                                                     | Example value |