Merge branch 'main' into km/logo-update

.vscode/extensions.json

@@ -3,9 +3,11 @@
       "astro-build.astro-vscode",
       "esbenp.prettier-vscode",
       "yzhang.markdown-all-in-one",
+      "docsmsft.docs-markdown",
       "ms-playwright.playwright",
       "streetsidesoftware.code-spell-checker",
-      "unifiedjs.vscode-mdx"
+      "unifiedjs.vscode-mdx",
+      "DavidAnson.vscode-markdownlint"
     ],
     "unwantedRecommendations": []
   }

.vscode/settings.json

@@ -5,4 +5,10 @@
     },
     "[markdown]": {
     },
+    "markdownlint.run": "onSave",
+    "markdownlint.config": {
+        "emphasis": { "style": "asterisk" },
+        "no-inline-html": false,
+        "ul-style": { "style": "dash" }
+    },
 }

README.md

@@ -1,21 +1,23 @@
+# Octopus docs
+
 This repository contains the documentation for [Octopus Deploy](https://octopus.com/docs).
 
 Contributions to help improve this documentation are welcome, however, you must sign the [Contribution License Agreement (CLA)](https://cla-assistant.io/OctopusDeploy/docs) before we can accept your contribution.
 
 See the [Octopus style guide](https://www.octopus.design/932c0f1a9/p/26f741-writing) for information including:
 
-* [Markdown quick reference](https://www.octopus.design/932c0f1a9/p/074e30-markdown-reference)
-* [Capitalization](https://www.octopus.design/932c0f1a9/p/457bc4-grammar-rules/t/03e016)
-* [Working with images](https://www.octopus.design/932c0f1a9/p/5061d7-working-with-images)
+- [Markdown quick reference](https://www.octopus.design/932c0f1a9/p/074e30-markdown-reference)
+- [Capitalization](https://www.octopus.design/932c0f1a9/p/457bc4-grammar-rules/t/03e016)
+- [Working with images](https://www.octopus.design/932c0f1a9/p/5061d7-working-with-images)
 
 ## How to contribute a change to the docs
 
-* The `main` branch has the latest version of the docs
-* Fork this repo and create a branch for your changes
-* Make the changes you'd like to contribute
-* Submit a pull request (PR) to master with your changes and include a comment explaining the changes
-* Sign the [Contribution License Agreement (CLA)](https://cla-assistant.io/OctopusDeploy/docs)
-* We'll review your PR and accept it or suggest changes
+- The `main` branch has the latest version of the docs
+- Fork this repo and create a branch for your changes
+- Make the changes you'd like to contribute
+- Submit a pull request (PR) to master with your changes and include a comment explaining the changes
+- Sign the [Contribution License Agreement (CLA)](https://cla-assistant.io/OctopusDeploy/docs)
+- We'll review your PR and accept it or suggest changes
 
 ### Default values
 
@@ -39,7 +41,7 @@ When you raise a pull request, the following checks will take place:
 
 You can run the tests locally using:
 
-```
+```bash
 pnpm test
 ```
 
@@ -52,7 +54,7 @@ The most common failures are:
 
 You can run the spell check locally using:
 
-```
+```bash
 pnpm spellcheck
 ```
 
@@ -103,13 +105,13 @@ You can use the Front Matter dashboard to find content, media, and snippets - or
 
 The pages are in the exact page shown on the website, so you can easily translate them. For example:
 
-```
+```bash
 https://octopus.com/docs/infrastructure/deployment-targets/tentacle
 ```
 
 Can be found in the exact same path within `src/pages/`
 
-```
+```bash
 \docs\src\pages\docs\infrastructure\deployment-targets\tentacle
 ```
 
@@ -123,17 +125,17 @@ No page should ever be deleted! When a page moves or is retired, it should be ch
 
 The below shows the complete contents of a redirect page that sends users from:
 
-```
+```bash
 /docs/administration/authentication/authentication-providers/azure-ad-authentication
 ```
 
 To the new location:
 
-```
+```bash
 /docs/security/authentication/azure-ad-authentication
 ```
 
-```
+```yaml
 ---
 layout: src/layouts/Redirect.astro
 title: Redirect
@@ -195,13 +197,15 @@ Within an MDX file, this looks like a code block and will error. Escape the stat
 ## Switching between spaces \{#switching-between-spaces}
 ```
 
+MDX files don't allow short-form links, instead of using `<https://example.com>` use `[https://example.com](https://example.com)`, or even better - put in useful link text, like `[example website](https://example.com)`.
+
 ## Docs page layout guidelines
 
 ### Title icons
 
 If you are updating a page in Docs which doesn't already have a title icon, please add one. Title icons can be added in the frontmatter for each page by adding a Font Awesome class in the `icon` entry: 
 
-```
+```yaml
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
@@ -221,7 +225,7 @@ hideInThisSectionHeader: true
 
 Product screenshots used in Docs should reflect the UI in the latest version of Octopus. The `figure` component will automatically add a curved border and outline to your image:
 
-```
+```markdown
 :::figure
 ![](/docs/octopus-cloud/images/octopus-cloud-architecture-diagram.png)
 :::
@@ -233,6 +237,6 @@ Images should be uploaded to the folder that relates to the position of the page
 
 Do not use call out / info boxes in the main body of docs pages to reference how features worked in earlier versions of Octopus. This information should be moved to the bottom of docs pages under an 'Older versions' heading. For example, you might add a note like this under the 'Older versions' heading:
 
-```
+```markdown
 In versions earlier than 2024.x, you'll find the page to add a feed under the Projects menu -> Tenant Variables
 ```

cspell.json

@@ -18,6 +18,7 @@
         "pnpm-lock.yaml",
         "docs/credits.md",
         ".octopus/**",
+        ".vscode/**",
         ".github/**",
         "src/pages/report/**",
         "public/docs/js/**",

dictionary-octopus.txt

@@ -107,6 +107,7 @@ emptytitle
 entra
 environmentids
 eprintfn
+esac
 expressjs
 externalgroups
 externalusers
@@ -392,6 +393,7 @@ SSPI
 SSRS
 statefulset
 statefulsets
+stepsprodpackages.blob.core.windows.net
 sthumb
 strconv
 struct
@@ -417,6 +419,7 @@ tfvar
 tfvars
 TFVC
 thepassword
+timespan
 tlsv1
 tmpfs
 Toolsets

src/pages/docs/administration/migrate-spaces-with-octoterra/index.md

@@ -91,7 +91,7 @@ These are the prerequisites for migrating an Octopus space with the Octoterra Wi
 
 * [Backup](https://octopus.com/docs/administration/data/backup-and-restore) and [update](https://octopus.com/docs/administration/upgrading) your Octopus instance.
 * [Backup](https://octopus.com/docs/administration/data/backup-and-restore) your Octopus instance again before the migration.
-* Download the Octoterra Wizard from [GitHub](https://github.com/mcasperson/OctoterraWizard).
+* Download the Octoterra Wizard from [GitHub](https://github.com/OctopusSolutionsEngineering/OctoterraWizard).
 * Install [Terraform](https://developer.hashicorp.com/terraform/install) on your local workstation.
 * [Create an API key](https://octopus.com/docs/octopus-rest-api/how-to-create-an-api-key) for the source Octopus instance.
 * [Create an API key](https://octopus.com/docs/octopus-rest-api/how-to-create-an-api-key) for the destination Octopus instance.
@@ -112,7 +112,7 @@ The final prompts do not involve any input. They automate the process of install
 
 Each sensitive variable must have a unique name and no scopes in order for Octopus to expose sensitive variables defined in the project and in library variable sets to the Terraform module created by Octoterra.
 
-However, it is common for sensitive variables to share a name use scopes to define unique values for different contexts. For example, you may have two sensitive variables called `Database.Password`, with the first variable scoped to the `Dev` environment, and the second scoped to the `Production` environment. This is demonstrated in the screenshot below:
+However, it is common for sensitive variables to share a name and use scopes to define unique values for different contexts. For example, you may have two sensitive variables called `Database.Password`, with the first variable scoped to the `Dev` environment, and the second scoped to the `Production` environment. This is demonstrated in the screenshot below:
 
 ![Sensitive project variables](/docs/administration/migrate-spaces-with-octoterra/sensitive-variables.png)
 
@@ -255,12 +255,12 @@ The first approach is to apply these changes in multiple steps:
 The second approach is to delete any projects on the destination server and recreate them with the new settings:
 
 1. On the source server, create the new space level resources and update projects to point to them.
-2. One the destination server, delete any projects that were modified on the source server.
+2. On the destination server, delete any projects that were modified on the source server.
 3. At this point no projects on either the source or destination server refer to the old space level resources.
 4. Deploy both the space and project level changes to the destination server.
 
 :::div{.hint}
-Projects are configured to ignore changes to the `project_group_id` and `name` with the following [lifecycle meta-argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle:
+Projects are configured to ignore changes to the `project_group_id` and `name` with the following [lifecycle meta-argument](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle):
 
 ```
   lifecycle {

src/pages/docs/best-practices/deployments/variables.md

@@ -1,7 +1,7 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-10-04
+modDate: 2023-11-18
 title: Variable Recommendations
 description: Guidelines and recommendations for configuring variables in Octopus Deploy.
 navOrder: 60
@@ -74,8 +74,6 @@ For configurations that differ per environment, our recommendation is to use a c
 
 Octopus Deploy can set an environment variable or configuration value during deployment to indicate which environment-specific configuration file to use.  Or, if you are using .NET Framework, you can leverage [configuration file transforms](/docs/projects/steps/configuration-features/configuration-transforms).
 
-For other items,   
-
 ## Variable Sets
 
 [Variable Sets](/docs/projects/variables/library-variable-sets) are a great way to share variables between projects.  We recommend the following when creating variable sets.

src/pages/docs/deployments/azure/cloud-services/getting-started-with-azure-cloud-services.md

@@ -1,9 +1,9 @@
 ---
 layout: src/layouts/Redirect.astro
 title: Redirect
-redirect: https://octopus.com/docs/deployments/azure/cloud-services
+redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure
 pubDate:  2023-01-01
 navSearch: false
 navSitemap: false
 navMenu: false
----
+---

src/pages/docs/deployments/azure/cloud-services/index.md

@@ -0,0 +1,10 @@
+---
+layout: src/layouts/Redirect.astro
+title: Redirect
+redirect: https://octopus.com/docs/infrastructure/deployment-targets/azure
+pubDate:  2023-01-01
+navSearch: false
+navSitemap: false
+navMenu: false
+hideInThisSectionHeader: true
+---