Fix markdownlint violations in machine-policies.mdx

LukeButters · claude · LukeButters · commit b8d08b7c3dde · 2026-07-21T12:17:05.000+10:00
CI lints the full content of any touched file, not just the diff, so
this pre-existing lint debt (missing blank lines around headings/lists/
fences, missing image alt text, bold-as-heading, hard tabs, trailing
whitespace, a stale link fragment) was blocking this PR. Converts bold
pseudo-headings to real headings and adds descriptive alt text to
images based on surrounding context.

Co-Authored-By: Claude Sonnet 5 &lt;noreply@anthropic.com&gt;
diff --git a/src/pages/docs/infrastructure/deployment-targets/machine-policies.mdx b/src/pages/docs/infrastructure/deployment-targets/machine-policies.mdx
@@ -21,9 +21,10 @@ You can access the machine policies by navigating to **Infrastructure ➜ Machin
 [Getting Started - Machine Policies](https://www.youtube.com/watch?v=uEjXuPttRO4)
 
 ## Default machine policy
+
 By default, Octopus Deploy comes with a default configured machine policy with the following rules:
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-default-policy.png)
+![Default machine policy settings](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-default-policy.png)
 :::
 
 This machine policy cannot be deleted however it can be edited and any new deployment targets without an explicitly assigned machine policy will use the default one. Other machine policies will also inherit the bash/powershell scripts used for health checking from the default policy unless they have one explicitly set.
@@ -44,13 +45,12 @@ A *healthy* deployment target completes a health check without any errors or war
 You can review the health status of you deployment targets by navigating to **Infrastructure ➜ Deployment Targets**.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-deployment-target-overview.png)
+![Deployment targets overview showing health status](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-deployment-target-overview.png)
 :::
 
-
 ### Health check step
 
-It's also possible to run a health check as part of a deployment or runbook using the built-in [health check step](/docs/projects/built-in-step-templates/health-check). 
+It's also possible to run a health check as part of a deployment or runbook using the built-in [health check step](/docs/projects/built-in-step-templates/health-check).
 
 This step allows a deployment target that was created in the currently executing deployment to be confirmed as healthy and then added to the running deployment for subsequent steps.
 
@@ -64,15 +64,16 @@ After creating a new Tentacle or SSH Target, Octopus Deploy will automatically s
 2. Click the ... overflow menu and select **Check Health**. If you have multiple deployment targets that support health checking it will start health checks for each of them.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-check-health.png)
+![Check Health option in the deployment targets overflow menu](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-check-health.png)
 :::
 
 However if you would like to check the health of a single deployment target you can do the following:
+
 1. Select the deployment target you would like to health check.
 2. Click on the **Connectivity** tab then click on the **Check Health** button on the top right of the page.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-deployment-target-connectivity.png)
+![Check Health button on the deployment target Connectivity tab](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-deployment-target-connectivity.png)
 :::
 
 The first time you complete a health check on a Tentacle or SSH Target, you will see health warnings and that Calamari needs to be installed.
@@ -85,99 +86,106 @@ Octopus will automatically push the latest version of Calamari with your first d
 2. Click the ... overflow menu and select **Upgrade Calamari on Deployment Targets**.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-update-calamari.png)
+![Upgrade Calamari on Deployment Targets option in the overflow menu](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-update-calamari.png)
 :::
 
 Like with the health check if you would rather just update Calamari on a single deployment target you can achieve this by:
+
 1. Select the deployment target you would like to update Calamari on.
 2. Click on the **Connectivity** tab then click on the **Update Calamari** button.
 
 ## Health check configuration
+
 ### Health check schedule type
+
 A health check can be scheduled in the following ways:
 
-**Never**
+#### Never
 
 No automatic health checks will be scheduled, when this option is selected. Manual health checks can still be run when desired.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-never.png)
+![Health check schedule set to Never](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-never.png)
 :::
 
-**Interval**
+#### Interval
 
 A health check will be scheduled after every X duration(X = days/hours/minutes)
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-interval.png)
+![Health check schedule set to Interval](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-interval.png)
 :::
 
-**Cron expression**
+#### Cron expression
 
 A health check will be scheduled in accordance to the valid cron expression. You can also choose the timezone the cron expression should adhere to.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-cron.png)
+![Health check schedule set to Cron expression](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-cron.png)
 :::
 
 ### Health check type
+
 You can configure health checks to run scripts on Tentacle or SSH deployment targets, or just check that a connection can be established with the Tentacle or SSH deployment targets.
 
-**Run health check script**
+#### Run health check script
 
 Machine policies allow the configuration of custom health check scripts for Tentacle and SSH deployment targets. While we do not expose the full underlying script that runs during health checks, we give you an entry point to inject your own custom scripts.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-type-script.png)
+![Health check type set to Run health check scripts](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-type-script.png)
 :::
-By default, machine policies will inherit the script from the default machine policy if one has not been defined. For more details on providing a custom script see the section [Custom health check script](#custom-health-check-script)
+By default, machine policies will inherit the script from the default machine policy if one has not been defined. For more details on providing a custom script see the section [Custom health check script](#custom-health-check-scripts)
 
-**Connection test**
+#### Connection test
 
 The health check will only perform a basic connection test to see if the deployment target is reachable. This option is recommended if you are using the raw scripting feature.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-type-connection.png)
+![Health check type set to Only perform connection test](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-health-check-type-connection.png)
 :::
 
 ### Machine behavior during health checks
+
 This setting controls what the expected behavior of machines should be during a health check.
 
-**Unavailable causes health checks to fail**
+#### Unavailable causes health checks to fail
 
 If a machine is unavailable during an attempted health check it will cause the check to be failed.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-health-check-default.png)
+![Unavailable deployment targets causing health checks to fail](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-health-check-default.png)
 :::
 
-**Ignore machines that are unavailable during health checks**
+#### Ignore machines that are unavailable during health checks
 
 By default, health checks fail if any deployment targets are unavailable during the health check. Machine policies offer an option to ignore machines if they are unavailable during a health check:
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-health-check-ignore.png)
+![Option to ignore unavailable machines during health checks](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-health-check-ignore.png)
 :::
 
 By selecting **Unavailable machines will not cause health checks to fail,** any deployment targets that Octopus cannot contact during a health check will be skipped and the health check marked as successful. If the target is contactable but encounters an error or warning, the usual health check behavior will proceed (i.e., a warning will be reported or the health check will fail with an error).
 
 ### Custom health check script \{#custom-health-check-scripts}
+
 When the selected health check type is "Run health check scripts" you can provide script(s) that will execute during the health check.
 
-**Default PowerShell health check script**
+#### Default PowerShell health check script
 
 Here is the default custom health check script for PowerShell that checks disk space:
 
 ```powershell
 $freeDiskSpaceThreshold = 5GB
 Try {
-	Get-WmiObject win32_LogicalDisk -ErrorAction Stop  | ? { ($_.DriveType -eq 3) -and ($_.FreeSpace -ne $null)} |  % { CheckDriveCapacity @{Name =$_.DeviceId; FreeSpace=$_.FreeSpace} }
+    Get-WmiObject win32_LogicalDisk -ErrorAction Stop  | ? { ($_.DriveType -eq 3) -and ($_.FreeSpace -ne $null)} |  % { CheckDriveCapacity @{Name =$_.DeviceId; FreeSpace=$_.FreeSpace} }
 } Catch [System.Runtime.InteropServices.COMException] {
-	Get-WmiObject win32_Volume | ? { ($_.DriveType -eq 3) -and ($_.FreeSpace -ne $null) -and ($_.DriveLetter -ne $null)} | % { CheckDriveCapacity @{Name =$_.DriveLetter; FreeSpace=$_.FreeSpace} }
-	Get-WmiObject Win32_MappedLogicalDisk | ? { ($_.FreeSpace -ne $null) -and ($_.DeviceId -ne $null)} | % { CheckDriveCapacity @{Name =$_.DeviceId; FreeSpace=$_.FreeSpace} }
+    Get-WmiObject win32_Volume | ? { ($_.DriveType -eq 3) -and ($_.FreeSpace -ne $null) -and ($_.DriveLetter -ne $null)} | % { CheckDriveCapacity @{Name =$_.DriveLetter; FreeSpace=$_.FreeSpace} }
+    Get-WmiObject Win32_MappedLogicalDisk | ? { ($_.FreeSpace -ne $null) -and ($_.DeviceId -ne $null)} | % { CheckDriveCapacity @{Name =$_.DeviceId; FreeSpace=$_.FreeSpace} }
 }
 ```
+
 The function *CheckDriveCapacity* informs you about how much space is available on your deployment target's local hard disk and will write a warning if the free disk space is less than this threshold. You can add additional PowerShell to this script to customize your health checks as you wish, modify or remove the disk space checking altogether. It's entirely up to you! Just remember, you can copy and paste the original script above *back* into your machine policy if you run into any problems and wish to get back to the default behavior.
 
-**Set the status**
+#### Set the status
 
 A health check script can set the status of a target by returning a non-zero exit code or by writing a service message during the health check. PowerShell based deployment targets can use *Write-Warning*, *Write-Error* and *Fail-HealthCheck* to convey a healthy with warnings or unhealthy status:
 
-**PowerShell health check service messages**
+#### PowerShell health check service messages
 
 ```powershell
 # For setting a health status of Healthy with Warnings:
@@ -191,7 +199,7 @@ Bash targets do not include a disk space check by default like PowerShell target
 
 Bash deployment targets can use *echo\_warning*, *echo\_error* and *fail\_healthcheck* to convey a *healthy with warnings* or *unhealthy* status:
 
-**Bash Health Check Service Messages**
+#### Bash Health Check Service Messages
 
 ```bash
 # For setting a health status of Healthy with Warnings:
@@ -209,7 +217,7 @@ When using a custom health check script, the script execution through Calamari i
 
 ## Configure how Calamari, Tentacle and Kubernetes agents are updated \{#configure-machine-updates}
 
-Brand new Tentacle, Kubernetes agent and SSH endpoints require the installation of Calamari to perform a deployment.  Also, if Calamari is updated, the Octopus Server will push the update to Tentacle, Kubernetes agent and SSH endpoints. 
+Brand new Tentacle, Kubernetes agent and SSH endpoints require the installation of Calamari to perform a deployment.  Also, if Calamari is updated, the Octopus Server will push the update to Tentacle, Kubernetes agent and SSH endpoints.
 When there is a Tentacle or Kubernetes agent update, Octopus can automatically update Tentacle and Kubernetes agent endpoints.  Machine policies allow the customization of when Calamari, Tentacle and Kubernetes agent updates occur.
 
 :::figure
@@ -221,7 +229,7 @@ By default, Calamari will be installed or updated when a machine is involved in
 - the first time a machine is added to Octopus and then subsequently when it is involved in a deployment.
 - any time Octopus detects Calamari is out of date (after health checks for example).
 
-Tentacle and Kubernetes agents can be toggled to manually or automatically update.  If **Automatically** is selected, Octopus will start a task to update Tentacles and Kubernetes agents whenever Octopus detects that there is a pending Tentacle or Kubernetes agents upgrade (after health checks for example). 
+Tentacle and Kubernetes agents can be toggled to manually or automatically update.  If **Automatically** is selected, Octopus will start a task to update Tentacles and Kubernetes agents whenever Octopus detects that there is a pending Tentacle or Kubernetes agents upgrade (after health checks for example).
 
 Conversely, Octopus will not automatically update Tentacle or Kubernetes agents but instead will display a prompt to begin a Tentacle and Kubernetes agents update on the Deployment Targets and Environments screens.
 
@@ -251,30 +259,31 @@ You can configure whether Octopus Deploy should re-attempt failed communications
 
 - With this setting **Enabled**, if a network error occurs, Octopus will re-attempt communication with the Tentacle for the amount of time configured. However, continued network errors will cause a failure.
 
-
 :::div{.warning}
 Using this setting with a Tentacle that runs on ephemeral storage will introduce the possibility that a script could run twice. For example, when running Tentacle in Docker without a mount. It is recommended to run Tentacle on a persistent file system.
 :::
 
 ### Retry durations
+
 You can configure the amount of time allowed for Octopus to re-attempt failed communication with Tentacle. There are two duration configurations available:
 
 - **Deployment or Runbook Run**
-- **Health Check** 
+- **Health Check**
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-tentacle-error-recovery-retry-duration.png)
+![Retry duration settings for deployment, runbook run and health check](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-tentacle-error-recovery-retry-duration.png)
 :::
 
 ### Step Retries and execution timeouts
+
 If you would like to retry a particular step within the deployment process for other types of temporary or transient errors, that can be [configured separately](/docs/projects/steps/conditions/#retries-and-execution-timeouts).
 
 ## Automatically delete machines
 
 Machine policies can be configured to automatically remove unavailable machines after a time period.  When a health check runs, Octopus detects if machines are unavailable (cannot be contacted). When the **Automatically delete unavailable machines** option is set, Octopus checks how long a machine has been unavailable.  If the specified time period has elapsed, the machine is permanently deleted from Octopus.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-clean-up-unavailable.png)
+![Automatically delete unavailable machines setting](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-clean-up-unavailable.png)
 :::
 
 ## Package cache retention policy
@@ -286,7 +295,7 @@ Configurable machine package cache retention was introduced in **Octopus 2025.3*
 The machine package cache retention policy ensures that packages are periodically removed from the machine cache. This is handled by Octopus by default, but can be configured per machine policy as required.
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-package-cache-retention.png)
+![Package cache retention policy settings](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-package-cache-retention.png)
 :::
 
 ## Machine connectivity configuration
@@ -299,48 +308,50 @@ For Tentacles, [Retry Durations](#recover-from-communication-errors) should be u
 
 Machine policies define rules for how long to wait for a connection to be established to a Tentacle or SSH target as well as how it should retry the connection if the initial attempts do not succeed.
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-timeout-retries.png)
+![Connection timeout and retry settings](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-timeout-retries.png)
 :::
 
-**Connect timeout**
+#### Connect timeout
 
 How long in hours/minutes/seconds to wait for a Listening Tentacle or SSH target respond to a connection before timing out. Depending on what operating system the machine is running could potentially mean the timeout is shorter than expected.
 
-**Retry attempts**
+#### Retry attempts
 
 How many times the connection to the Listening Tentacle or SSH target should be retried before failing the health check.
 
-**Retry wait interval**
+#### Retry wait interval
 
 How long to wait between connection retries.
 
-**Retry time limit**
+#### Retry time limit
 
 Maximum time limit for how long retries can be attempted for.
 For example, if you have the following configuration:
+
 - Retry time limit: 1 minute.
 - Retry attempts: 4.
 - Retry interval: 30 seconds.
 
 In this scenario only a maximum of 2 retries could be attempted before reaching the time limit.
 
 ### Polling request queue timeout
+
 This setting controls how long Octopus Deploy will wait before cancelling a task in a polling Tentacle's queue. For more details on what the Polling Tentacle queue is see the documentation on [Tentacle communication modes](/docs/infrastructure/deployment-targets/tentacle/tentacle-communication#polling-tentacles)
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-polling-queue.png)
+![Polling request queue timeout setting](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-polling-queue.png)
 :::
 
 ## Assign machine policies to machines
 
 Assign a machine policy to a machine by selecting a machine from the *Deployment Targets* or *Workers* screen and using the *Policy* drop down to select the machine policy:
 
 :::figure
-![](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-assign-policy.png)
+![Assigning a machine policy to a deployment target](/docs/img/infrastructure/deployment-targets/machine-policies/machine-policies-connectivity-assign-policy.png)
 :::
 
 Machine policy can also be set from the command line by using the --policy argument:
 
-**Setting machine policy**
+### Setting machine policy
 
 ```powershell
 Tentacle.exe register-with --instance "Tentacle" --server "http://YOUR_OCTOPUS" --apiKey="API-YOUR_API_KEY" --role "web-server" --environment "Staging" --comms-style TentaclePassive --policy "Transient machines"
