Merge pull request #7348 from umbraco/cloud/CleanUp

Clean some articles

Author: sofietoft

.github/styles/UmbracoDocs/LinkTextClarity.yml

@@ -5,5 +5,11 @@ description: >
   Descriptive link text improves accessibility and SEO by clearly indicating
   where the link leads, rather than using vague terms.
 level: warning
-raw:
-  - '(?i)\[(?:click here|here)\]\([^)]*\)'
+ignorecase: true
+scope: raw
+nonword: true
+tokens:
+  - '\[\s*here\s*\]'
+  - '\[\s*click here\s*\]'
+  - '\[\s*read more\s*\]'
+  - '\[\s*more info\s*\]'

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/azure-devops.md

@@ -234,7 +234,9 @@ If you want to customize the artifact take a look at [Artifact Best Practice](..
 The `cloud-deployment.yml` shows how you can deploy to a named environment of your Cloud project. The sample shows how to request the deployment and wait for cloud to finish the operation.
 
 {% hint style="info" %}
+
 If you have frontend assets that needs to be built (using tools like npm/yarn or others), you should add the needed steps before `cloudPrepareArtifact`. This is to ensure that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud.
+
 {% endhint %}
 
 ## Next step

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/samplecicdpipeline/github-actions.md

@@ -83,6 +83,7 @@ Now go to the **Variables** tab
 * Create a `repository variable` called `TARGET_ENVIRONMENT_ALIAS` and enter the environment alias you selected earlier.
 
 {% hint style="info" %}
+
 If you want to use other names for the secrets and variables, you need to rename the `secrets` and `with` variables in each of `main.yml`'s jobs.
 
 ```yaml
@@ -110,6 +111,7 @@ jobs:
     with:
       targetEnvironmentAlias: ${{ vars.TARGET_ENVIRONMENT_ALIAS }} # change the part inside the curly braces
 ```
+
 {% endhint %}
 
 Now GitHub is set up with the needed information to be able to run a deployment back to Umbraco Cloud.
@@ -264,7 +266,9 @@ If you want to customize the artifact take a look at [Artifact Best Practice](..
 The `cloud-deployment.yml` shows how you can deploy to a named environment of your Cloud project. The sample shows how to request the deployment and wait for cloud to finish the operation.
 
 {% hint style="info" %}
+
 If you have frontend assets that needs to be built (using tools like npm/yarn or others), you should add the needed steps before `cloud-artifact`. This is to ensure that the fresh frontend assets will be part of the package to be sent to Umbraco Cloud.
+
 {% endhint %}
 
 ## Next step

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/troubleshooting.md

@@ -26,7 +26,7 @@ The mechanism to determine changes since the last deployment is not able to do s
 }
 ```
 
-You will need to _manually_ make sure that all latest changes on your left-most mainline environment in cloud is also present in your local copy.
+You need to _manually_ make sure that all latest changes on your left-most mainline environment is also present in your local copy.
 
 Once this is done you can run a new deployment, where you skip the cloud-sync step.
 
@@ -58,8 +58,8 @@ Once that has been done, you should run a new deployment without the `cloud-sync
 For Azure DevOps, see the [Skip cloud-sync in Azure DevOps](troubleshooting.md#skip-cloud-sync-in-azure-devops) section.
 
 1. Ensure your GitHub repository is up-to-date with any changes in your Umbraco Cloud environment.
-2. Locate the main.yml file in the following directory: {projectname}.github\workflows on tour local project.
-3. Open the main.yml file in a text editor and navigate to the “jobs” section.
+2. Locate the `main.yml` file in the following directory: `{projectname}.github\workflows` on tour local project.
+3. Open the `main.yml` file in a text editor and navigate to the “jobs” section.
 4. Comment out the entire “cloud-sync” section and the “needs: cloud-sync” under “cloud-deployment”. An example is provided in the screenshot below.
 
 ![Cloud sync code highlight](../../set-up-your-project/project-settings/images/cloudsync.png)
@@ -108,11 +108,11 @@ You can see an example of how you could zip your repository before uploading it,
 
 ## Deployment failed
 
-### File missing: The .umbraco file cannot be found in the root of the repository
+### File missing: The `.umbraco` file cannot be found in the root of the repository
 
 The `.umbraco` file is missing or has been renamed. This file needs to be present in the root of the zipped package.
 
-### File format Error: The .umbraco file is not valid
+### File format Error: The `.umbraco` file is not valid
 
 The `.umbraco` file has invalid characters. Sometimes people need to change the repository's folder structure and the default project's name. Ensure that the base field does not use backslashes ('') as the folder denominator.
 
@@ -142,7 +142,7 @@ We recommend aligning the package versions in your _.csproj_ files with the high
 
 If you have orphaned csproj-files you should remove them or rename them. Orphaned would be backup _.csproj_ files or files not referenced by any of the main project files nor referenced in a _.sln_ file.
 
-### Could not find '/app/work/repository/Readme.md' to stat: No such file or directory
+### Could not find `/app/work/repository/Readme.md` to stat: No such file or directory
 
 In some instances we see an issue where filename casing is causing an error.
 
@@ -170,18 +170,18 @@ Once the marker file is removed, run your pipeline again.
 
 ### Unable to determine environment by its {environment-id}
 
-This happens when you use the CI/CD feature of Umbraco Cloud to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message:
+This happens when using CI/CD to deploy changes to your live environment, and later add a new Cloud environment. Your environment will fail to boot up and will show the following error message:
 
 ```
 “System.InvalidOperationException: Unable to determine environment by its {environment-id}”
 ```
 
-This issue arises because the environment is missing in the local umbraco-cloud.json file. To resolve this issue, follow these steps:
+This issue arises because the environment is missing in the local `umbraco-cloud.json` file. To resolve this issue, follow these steps:
 
 1. Navigate to Kudu in your Live environment
 2. Select “Debug console” and choose “CMD”.
 3. Find the umbraco-cloud.json file. Path to this file may vary depending on your setup, but the default location on cloud is C:\home\site\repository\src\UmbracoProject
 4. Click ‘edit’ on the file and copy all its content. This content is consistent across environments, so it’s safe to do so.
-5. Paste the copied content into the umbraco-cloud.json file in your local project and push the changes.
+5. Paste the copied content into the `umbraco-cloud.json` file in your local project and push the changes.
 
 After completing these steps, your left-most mainline environment should be correctly registered across all environments, allowing you to continue your work without any issues.

umbraco-cloud/build-and-customize-your-solution/handle-deployments-and-environments/umbraco-cicd/umbracocloudapi.md

@@ -2,9 +2,8 @@
 
 The Umbraco Cloud API serves as a publicly accessible endpoint that customers can utilize to execute relevant tasks.
 
-While its initial focus is on automating and managing deployments in Umbraco Cloud projects via the "Umbraco CI/CD Flow," future enhancements will broaden its capabilities to encompass a wider range of activities and options for Umbraco Cloud users.
-
 {% hint style="info" %}
+
 ### Changes between endpoints for version 1 and 2
 
 With the endpoints for version 2, you are given more control over the process.
@@ -17,7 +16,8 @@ These are the most important differences between the V1 and V2 endpoints:
 
 [Do you want to migrate from V1 to V2 endpoints?](samplecicdpipeline/migrate.md)
 
-The V1 endpoints are still available, you can see the [V1 api documentation here](v1-umbraco-cloud-api.md).
+[The V1 endpoints are still available](v1-umbraco-cloud-api.md).
+
 {% endhint %}
 
 ## Getting started
@@ -53,8 +53,9 @@ The two elements to be used for the authentication are:
 
 By including the API key header in your HTTP requests, you ensure secure access to your Umbraco Cloud project's resources.
 
-For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions.\
-It's important to note that each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project.
+For enhanced security, it's crucial to store the provided API key in a secure location. Options include a variable group in Azure DevOps or using the Secrets feature in GitHub Actions.
+
+Each API key is tightly coupled with a specific Umbraco Cloud project and can only be used for deployments related to that project.
 
 ### How to authenticate your requests
 
@@ -231,16 +232,16 @@ The response from the API should be an HTTP 201 Created response including a `de
 You can use the deploymentId to query the Get Deployment status endpoint.
 
 {% hint style="info" %}
-It is not recommended to enable the `skipVersionCheck`. This is to ensure that versions of the various Umbraco packages in the Cloud environment aren't overwritten by older versions. However, there may be instances where you would like to deploy an older artifact, and for those cases, it is possible to enable this setting to skip the step.
+It is not recommended to enable the `skipVersionCheck`. This is to ensure that versions of the different Umbraco packages in the Cloud environment aren't overwritten by older versions. There may be instances where you would like to deploy an older artifact. In those instances it is possible to enable this setting to skip the step.
 
-Enabling the `noBuildAndRestore` only disabled the restore and build inside the isolated instance. Once the system pushes the source code to the environment, the regular Cloud flow takes over, and a build and publish operation will run as usual. One minute or more can be saved during the deployment process by enabling this option.
+Enabling the `noBuildAndRestore` only disabled the restore and build inside the isolated instance. Once the system pushes the source code to the environment a build and publish operation will run as usual. One minute or more can be saved during the deployment process by enabling this option.
 {% endhint %}
 
 ### Get Deployment status
 
-To monitor the status of a deployment, you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API, and it requires both the `projectId` and the `deploymentId` obtained from previous steps to be included in the path.
+To monitor the status of a deployment, you can periodically query the 'Get Deployment Status' API. This API endpoint is an HTTP GET request to the Umbraco Cloud API. It requires both the `projectId` and the `deploymentId` obtained from previous steps to be included in the path.
 
-Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, in a simple project, you might choose to poll the API every 25 seconds for a duration of 15 minutes. These figures are just a starting point; the optimal polling frequency and duration may differ for your specific pipeline.
+Deployments in Umbraco services can take varying amounts of time to complete. Therefore, it's advisable to poll this API at regular intervals to stay updated on the deployment's current state. For example, you might choose to poll the API every 25 seconds for a duration of 15 minutes. These figures are a starting point. The optimal polling frequency and duration may differ for your specific pipeline.
 
 A new query parameter has been added to limit the deploymentStatusMessages. As a value for the query parameter you can use the `modifiedUtc` value from a previous response.
 
@@ -257,7 +258,8 @@ Umbraco-Cloud-Api-Key: {{apiKey}}
 Content-Type: application/json
 ```
 
-The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the `deploymentState` field will indicate either 'Completed' or 'Failed'.\
+The response from this API call will return the same deployment object in JSON format as you would receive from other API interactions. Ultimately, the `deploymentState` field will indicate either 'Completed' or 'Failed'.
+
 Should the deployment fail, check the `deploymentStatusMessages` for more information.
 
 ```json
@@ -353,15 +355,17 @@ Content-Type: application/json
 
 ```
 
-The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. On the other hand, if there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes.
+The API response will vary based on whether or not there are changes to report. If no changes are detected, you'll receive an HTTP 204 No Content status. If there are changes, the API will return an HTTP 200 OK status along with a git-patch file as the content. This git-patch file can then be applied to your local repository to sync it with the changes.
 
 {% hint style="info" %}
-It is only possible to generate git-patch files when the selected `deploymentId` points to a deployment where the `targetEnvironmentAlias` then, is the same as in this request.
+
+It is only possible to generate git-patch files when the selected `deploymentId` points to a deployment where the `targetEnvironmentAlias` is the same as in this request.
+
 {% endhint %}
 
 ## Possible errors
 
-When interacting with the Umbraco Cloud API, you may encounter various HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting:
+When interacting with the Umbraco Cloud API, you may encounter HTTP status codes that indicate the success or failure of your API request. Below is a table summarizing the possible status codes, their corresponding errors, and basic root causes to guide your troubleshooting:
 
 | Status Code | Error               | Basic Root Cause                                                                    |
 | ----------- | ------------------- | ----------------------------------------------------------------------------------- |