Initial rewrite of variable substitution concept page and updates to …

src/pages/docs/best-practices/deployments/deployment-and-runbook-processes.md

@@ -15,13 +15,14 @@ Deployment and runbook processes are the series of steps you specify to either d
 
 Aside from the intended usage, there is little difference between a deployment process and a runbook process.  Both can use the same steps.  Both can scope steps to run on specific environments.  Because of that, this section can apply to both the runbooks and deployment processes.
 
-When you run a runbook or do a deployment, all the output is written to the Task Log.  
+When you run a runbook or do a deployment, all the output is written to the Task Log.
 
 :::figure
 ![task log after a deployment](/docs/img/getting-started/best-practices/images/task-log.png)
 :::
 
-The top of the task log allows you to change the information shown.  
+The top of the task log allows you to change the information shown.
+
 - By default, the log level is set to Info, which means only Info, Warnings, and Errors messages are shown.  Changing to Verbose will show all messages.
 - By default, the screen will only show the 20 most recent messages for each step.  Changing the log tail to all will show all messages.
 - Clicking on the **RAW** button will show you all the messages without any formatting.
@@ -34,6 +35,7 @@ The task log represents the deployment or runbook run details but is typically u
 :::
 
 The summary includes:
+
 - List of all steps and any important messages.
 - The task history, which includes who triggered it and when it was triggered.
 - The list of previous deployments to this environment for this project.
@@ -50,7 +52,7 @@ Both the task log and artifacts can be downloaded; there is no need to create ar
 
 ## Logging
 
-You can never have too much logging when running custom PowerShell, Python, or Bash scripts in your deployment or runbook process.  
+You can never have too much logging when running custom PowerShell, Python, or Bash scripts in your deployment or runbook process.
 
 [Octopus Deploy](/docs/deployments/custom-scripts/logging-messages-in-scripts) supplies built-in logging utilities you can leverage in your scripts.  This is one of the few areas where it is okay to directly reference these functions instead of passing them in as parameters.
 
@@ -60,15 +62,15 @@ We also recommend leveraging the different logging levels as Octopus treats each
 - Information: This is shown in the task log by default.  Useful for logging status messages to the user.
 - Warning: Messages are highlighted in yellow in the task log. Helpful if something isn't quite right, but the script was able to recover.
 - Error: Messages are highlighted in red in the task log and task summary.  This message type is for what it says on the tin, error messages.
-- Highlight: Messages are highlighted in blue in the task log and task summary.  Use these for important messages you want to let the user know about. 
+- Highlight: Messages are highlighted in blue in the task log and task summary.  Use these for important messages you want to let the user know about.
 
 Putting information required for approvals in a log file can make it difficult to find.  Consider artifacts as an alternative.
 
 ## Step naming and descriptions
 
-We recommend having clear, concise names for your steps.  The step name is what appears in the task summary and task log.  
+We recommend having clear, concise names for your steps.  The step name is what appears in the task summary and task log.
 
-By default, Octopus Deploy will only run a step if the previous step is successful.  You can override that behavior, so it always runs, only runs on failure, or runs on a variable condition.  If you override that default behavior, then the name should include that in the step name. 
+By default, Octopus Deploy will only run a step if the previous step is successful.  You can override that behavior, so it always runs, only runs on failure, or runs on a variable condition.  If you override that default behavior, then the name should include that in the step name.
 
 Starting in **Octopus Deploy 2020.5**, you can add a description field to each step.  We highly recommend using that to help other users of your deployment process understand what each step is doing.
 
@@ -95,7 +97,7 @@ The deployment and runbook processes should be the same for all environments, ex
 
 When defining your runbook or deployment process, you can configure a run condition based on a variable.  Generally, that feature is used to skip over a specific step when a particular condition occurs.  For example, skip over a testing step if only .css or image files were deployed.
 
-Octopus Deploy provides an [extended variable syntax](/docs/projects/variables/variable-substitutions/#extended-syntax) that includes support for if/elseif/else/then statements.  While it is possible to have a complex if/then statement in run condition, we don't recommend it.  Instead, we recommend you run a script and set an [output variable](/docs/projects/variables/output-variables).  Use that output variable in the run condition.  Having the decision made in a script means you can easily test and debug it. 
+Octopus Deploy provides [conditional variable syntax](/docs/projects/variables/variable-substitutions/#conditionals) that includes support for if/elseif/else/then statements.  While it is possible to have a complex if/then statement in run condition, we don't recommend it.  Instead, we recommend you run a script and set an [output variable](/docs/projects/variables/output-variables).  Use that output variable in the run condition.  Having the decision made in a script means you can easily test and debug it.
 
 ## Further reading
 

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

@@ -53,7 +53,7 @@ Regardless of the notification technology (email, Slack, MS Teams, etc.), the re
 
 - Create a variable set called "Notifications" to house common variables used in those notifications.  Some variables can include pending notification message, email subject, and deployment or runbook run result message.
 - Send notifications when pausing for approval or manual intervention to let the approver know a deployment is waiting for them.  Example variable value: `#{Octopus.Project.Name} #{Octopus.Release.Number} to #{Octopus.Environment.Name} is awaiting approval.`
-- Always send notifications at the end of each deployment informing interested parties of the deployment status.  Use Octopus Deploy's built-in [extended variable syntax](/docs/projects/variables/variable-substitutions/#extended-syntax) to differentiate between successful and failed deployments. Example variable value: `#{Octopus.Project.Name} #{Octopus.Release.Number} to #{Octopus.Environment.Name} has #{if Octopus.Deployment.Error}failed#{else}completed successfully#{/if}`
+- Always send notifications at the end of each deployment informing interested parties of the deployment status.  Use Octopus Deploy's built-in [conditional variable syntax](/docs/projects/variables/variable-substitutions/#conditionals) to differentiate between successful and failed deployments. Example variable value: `#{Octopus.Project.Name} #{Octopus.Release.Number} to #{Octopus.Environment.Name} has #{if Octopus.Deployment.Error}failed#{else}completed successfully#{/if}`
 - Include a deep link in your message back to the deployment or runbook run. Example variable value `https://samples.octopus.app/app#/#{Octopus.Space.Id}/tasks/#{Octopus.Task.Id}`
 
 ## Further reading

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

@@ -12,11 +12,11 @@ hideInThisSection: true
 
 There are multiple levels of variables in Octopus Deploy:
 
-1.  Project 
-2.  Tenant 
-3.  Step Templates
-4.  Variable Set
-5.  System Variables
+1. Project
+2. Tenant
+3. Step Templates
+4. Variable Set
+5. System Variables
 
 Project, Tenant, and Step Template variables are associated with their specific item and cannot be shared.  Variable Sets can be shared between 1 to N Projects and Tenants.  System variables are variables provided by Octopus Deploy you can use during deployments.
 
@@ -30,8 +30,8 @@ Octopus Deploy provides the ability to replace values in your configuration file
 
 In addition to having the above levels of variables, there are also two categories of variables.
 
-1.  Variables used in configuration file replacement (connection strings, version number, etc.)
-2.  Variables specific to the deployment or runbook run (output variables, messages, accounts, etc.)
+1. Variables used in configuration file replacement (connection strings, version number, etc.)
+2. Variables specific to the deployment or runbook run (output variables, messages, accounts, etc.)
 
 ## Variable naming
 
@@ -50,10 +50,10 @@ These naming conventions only apply to variables used for a deployment or runboo
 
 One of Octopus Deploy's most used features is environmental variable scoping.  And with good reason, having the same process, only needing a specific value such as a connection string or domain name changed, ensures consistency during deployment.
 
-However, that has led some customers to attempt to make Octopus Deploy something other than what it is.  Octopus Deploy is not a configuration management tool, secret store, or feature flag provider.  Store the variables required for Octopus Deploy to successfully deploy your application, along with a minimum amount of configuration variables.  
+However, that has led some customers to attempt to make Octopus Deploy something other than what it is.  Octopus Deploy is not a configuration management tool, secret store, or feature flag provider.  Store the variables required for Octopus Deploy to successfully deploy your application, along with a minimum amount of configuration variables.
 
 :::div{.hint}
-Changing a feature flag or secret stored in Octopus Deploy requires you to deploy or run a runbook to update the file manually.  Leverage best-in-breed tools for storing secrets or feature flags that were designed with that use case in mind.  Octopus Deploy should store the necessary connection information to those platforms as sensitive variables.  It should update the appropriate configuration file entries or set environmental variables to connect successfully to those tools.  
+Changing a feature flag or secret stored in Octopus Deploy requires you to deploy or run a runbook to update the file manually.  Leverage best-in-breed tools for storing secrets or feature flags that were designed with that use case in mind.  Octopus Deploy should store the necessary connection information to those platforms as sensitive variables.  It should update the appropriate configuration file entries or set environmental variables to connect successfully to those tools.
 :::
 
 Some examples of configuration variables include:
@@ -64,7 +64,7 @@ Some examples of configuration variables include:
 - Server ports
 - Service URLs
 
-There are also variables only Octopus Deploy knows about.  These include the release version number, environment name, and deployment date. 
+There are also variables only Octopus Deploy knows about.  These include the release version number, environment name, and deployment date.
 
 For configurations that differ per environment, our recommendation is to use a combination of Octopus Deploy and configuration files stored in source control.  You'd have three levels of configuration files:
 
@@ -87,10 +87,11 @@ Octopus Deploy can set an environment variable or configuration value during dep
 A common scenario we've talked to customers about is restricting variable edit access to specific environments.  For example, a developer can edit any variables scoped to **development** and **test** environments, but not **staging** or **production** environments.  On paper this makes sense, in practice this causes messy handovers and claims of "it worked on my machine."  The developers working on the application know all the various settings and variables required for their application to work.
 
 Our recommendations for variable edit permissions are:
-- Variable edit permissions should be all or nothing, either a person can edit variables, or they cannot.  Don't scope permissions to environments.  Anyone responsible for the application should have permission to update variables (developers, lead developers, DB developers, etc.) along with operations (DBAs, web admins, sysadmins) who can create and update service accounts and passwords.  
+
+- Variable edit permissions should be all or nothing, either a person can edit variables, or they cannot.  Don't scope permissions to environments.  Anyone responsible for the application should have permission to update variables (developers, lead developers, DB developers, etc.) along with operations (DBAs, web admins, sysadmins) who can create and update service accounts and passwords.
 - Variable Sets can be shared across multiple projects.  Limit who can edit variable set variables to more experienced Octopus Deploy users, or people who understand "with great power comes great responsibility."  Typically, we see senior or lead developers along with operations people who have these permissions.  If you want to isolate an application, consider using [spaces](/docs/administration/spaces).
-- Leverage [sensitive variables](/docs/projects/variables/sensitive-variables) to encrypt and hide sensitive values such as usernames and passwords.  Sensitive variables are write-only in the Octopus UI and Octopus API.  
-- Use [composite variables](/docs/projects/variables/variable-substitutions/#binding-variables) to combine sensitive and non-sensitive values.  A typical use case is database connection strings.  Each language has a specific syntax.  In the screenshot below `Project.Database.ConnectionString` is the composite variable, with the username and password referenced by the composite variable, but they are separate sensitive variables. 
+- Leverage [sensitive variables](/docs/projects/variables/sensitive-variables) to encrypt and hide sensitive values such as usernames and passwords.  Sensitive variables are write-only in the Octopus UI and Octopus API.
+- Use [composite variables](/docs/projects/variables/variable-substitutions/#composite-variables) to combine sensitive and non-sensitive values.  A typical use case is database connection strings.  Each language has a specific syntax.  In the screenshot below `Project.Database.ConnectionString` is the composite variable, with the username and password referenced by the composite variable, but they are separate sensitive variables.
 
 :::figure
 ![composite variables](/docs/img/getting-started/best-practices/images/composite-variables.png)

src/pages/docs/deployments/terraform/terraform-output-variables/index.md

@@ -25,7 +25,7 @@ The JSON representation of the output variable is the result of calling `terrafo
 
 While the value only output (which would appear in the logs as a message similar to `Saving variable "Octopus.Action[Apply Template].Output.TerraformValueOutputs[test]" with the value only of "test"`) would look similar to this:
 
-```
+```text
 "hi there"
 ```
 
@@ -41,8 +41,8 @@ $value = $OctopusParameters["Octopus.Action[Apply Template].Output.TerraformValu
 $value = $OctopusParameters["Octopus.Action[Apply Template].Output.TerraformJsonOutputs[test]"] | ConvertFrom-Json  | select -ExpandProperty value
 ```
 
-The syntax for accessing JSON variables as covered by our [documentation here](/docs/projects/variables/variable-substitutions/#json-parsing) applies to both `TerraformJsonOutputs` as well as `TerraformValueOutputs`. However, the latter is less useful as it can also be a primitive value. In this case Octostache won't know that it should deserialize the value and will provide you with a JSON encoded result. It is therefore recommended to prefer `TerraformJsonOutputs` where possible. The following syntax can be used to access the value using the binding syntax:
+The syntax for accessing JSON variables as covered by our [documentation here](/docs/projects/variables/variable-substitutions/#json-variables) applies to both `TerraformJsonOutputs` as well as `TerraformValueOutputs`. However, the latter is less useful as it can also be a primitive value. In this case Octostache won't know that it should deserialize the value and will provide you with a JSON encoded result. It is therefore recommended to prefer `TerraformJsonOutputs` where possible. The following syntax can be used to access the value using the binding syntax:
 
-```
+```text
 #{Octopus.Action[Apply Template].Output.TerraformJsonOutputs[test].value}
-```
+```