Give code blocks a header with a language and copy button

astro.config.mjs

@@ -7,6 +7,7 @@ import { attributeMarkdown, wrapTables } from '/src/themes/octopus/utilities/cus
 import llmMdEmitter from './src/integrations/llm-md-emitter.ts';
 import pruneDist from './src/integrations/prune-dist.ts';
 import rehypeWbr from './src/plugins/rehype-wbr.js';
+import shikiCodeBlock from './src/plugins/shiki-code-block.js';
 
 // https://astro.build/config
 export default defineConfig({
@@ -25,11 +26,20 @@ export default defineConfig({
     ],
     markdown: {
         shikiConfig: {
-            theme: 'light-plus',
+            // Every token carries both sets. main.css picks the dark one up
+            // under html[data-theme='dark']
+            themes: {
+                light: 'light-plus',
+                dark: 'dark-plus'
+            },
+            defaultColor: 'light',
             // OCL is HCL-derived, so reuse the HCL grammar for ```ocl fences
             langAlias: {
                 ocl: 'hcl'
-            }
+            },
+            // A transformer, because rehype plugins registered through
+            // `processor` below never reach .mdx pages
+            transformers: [shikiCodeBlock()]
         },
         processor: unified({
             remarkPlugins: [

src/pages/components.mdx

@@ -358,6 +358,118 @@ The Link component is designed to provide a standardized way to display links wi
   </div>
 </div>
 
+### Code block
+
+Every fenced code block is given a header carrying its language and a copy
+button. There is no component to import, so this works in `.md` as well as
+`.mdx`.
+
+#### Label
+
+Text after the language on the opening fence becomes the block's label. Write
+one that says what the code does; the language is already shown on the right.
+
+````text
+```powershell Write a release marker into the repository
+Write-Host "Hello, World!"
+```
+````
+
+```powershell Write a release marker into the repository
+Write-Host "Hello, World!"
+```
+
+Without a label, the header carries the language and the copy button alone.
+
+```powershell
+Write-Host "Hello, World!"
+```
+
+#### Several languages
+
+Wrap one fence per language in `<details>` elements sharing a `data-group`. Each
+`<summary>` names its language, and the header offers them in a menu.
+
+````text
+<details data-group="components-code-block">
+<summary>PowerShell</summary>
+
+```powershell Rename a deployment target
+$machine = $repository.Machines.Get("machines-1");
+```
+
+</details>
+<details data-group="components-code-block">
+<summary>C#</summary>
+
+```csharp Rename a deployment target
+var machine = repository.Machines.Get("machines-1");
+```
+
+</details>
+````
+
+<details data-group="components-code-block">
+<summary>PowerShell</summary>
+
+```powershell Rename a deployment target
+$machine = $repository.Machines.Get("machines-1");
+$machine.Name = "Test Server 1";
+$repository.Machines.Modify($machine);
+```
+
+</details>
+<details data-group="components-code-block">
+<summary>C#</summary>
+
+```csharp Rename a deployment target
+var machine = repository.Machines.Get("machines-1");
+machine.Name = "Test Server 1";
+repository.Machines.Modify(machine);
+```
+
+</details>
+
+A group whose panels hold anything besides a single code block stays a tab list.
+
+#### Long blocks
+
+A block over 500px tall collapses, fading out at the cut. Clicking the code
+expands it, and clicking away collapses it again.
+
+```yaml A deployment process with every step spelled out
+steps:
+  - name: Approve the release
+    action: manual-intervention
+    instructions: Check the release notes before approving.
+  - name: Deploy to the cluster
+    action: kubernetes-deploy-raw-yaml
+    package: octopus/hello-world
+    namespace: production
+  - name: Smoke test
+    action: run-a-script
+    script: |
+      $response = Invoke-WebRequest -Uri "https://example.com/health"
+      if ($response.StatusCode -ne 200) { throw "Unhealthy" }
+  - name: Notify the team
+    action: send-email
+    to: releases@example.com
+    subject: Deployed #{Octopus.Release.Number}
+  - name: Tag the release
+    action: run-a-script
+    script: |
+      git tag "release/#{Octopus.Release.Number}"
+      git push origin --tags
+  - name: Update the changelog
+    action: run-a-script
+    script: |
+      Add-Content CHANGELOG.md "#{Octopus.Release.Number}"
+  - name: Close the change request
+    action: run-a-script
+    script: |
+      Invoke-RestMethod -Method Post -Uri "https://example.com/changes/close"
+```
+
 ## Layout
 
 ### Grid

src/pages/docs/deployments/custom-scripts/index.md

@@ -123,15 +123,15 @@ Sometimes a script launches a service or application that runs continuously. In
 <details data-group="deployments-custom-scripts">
 <summary>PowerShell</summary>
 
-```powershell PowerShell
+```powershell
 Start-Process MyService
 ```
 
 </details>
 <details data-group="deployments-custom-scripts">
 <summary>Bash</summary>
 
-```bash Bash
+```bash
 screen -d -m -S "MyService" MyService
 ```
 

src/pages/docs/deployments/custom-scripts/logging-messages-in-scripts.md

@@ -111,7 +111,7 @@ Progress messages will display and update a progress bar on your deployment task
 <details data-group="deployments-custom-scripts-logging-messages">
 <summary>PowerShell</summary>
 
-```ps PowerShell
+```ps
 Update-Progress 10
 Update-Progress 50 "We're halfway there!"
 ```
@@ -205,7 +205,7 @@ def updateprogress(progress, message=None):
 ```bash
 function encode_service_message_value
 {
-	echo -n "$1" | openssl enc -base64 -A
+ echo -n "$1" | openssl enc -base64 -A
 }
 
 echo "##octopus[progress percentage='$(encode_service_message_value "$1")' message='$(encode_service_message_value "$2")']"
@@ -216,7 +216,8 @@ echo "##octopus[progress percentage='$(encode_service_message_value "$1")' messa
 ## Service message
 
 The following service messages can be written directly to standard output which will be parsed by the server and the subsequent log lines written to standard output will be treated with the relevant log level.
-```
+
+```text Set the standard output log level
 ##octopus[stdout-ignore]
 ##octopus[stdout-error]
 ##octopus[stdout-warning]
@@ -226,23 +227,25 @@ The following service messages can be written directly to standard output which
 ```
 
 To return to the default standard output log level, write the following message:
-```
+
+```text Return to the default standard output log level
 ##octopus[stdout-default]
 ```
 
+The following service messages can be written directly to standard output which will be parsed by the server and the subsequent log lines written to standard error will be treated with the relevant log level.
 
-The following service messages can be written directly to standard output which will be parsed by the server and the subsequent log lines written to standard error will be treated with the relevant log level. 
-```
+```text Set the standard error log level
 ##octopus[stderr-ignore]
 ##octopus[stderr-error]
 ##octopus[stderr-progress]
 ##octopus[stderr-output]
 ```
 
-- `stderr-progress` will cause error log lines to be written as `verbose` log lines. 
-- `stderr-output` will cause error log lines to be written as `info` log lines (standard output). Requires version `2025.3`. 
+- `stderr-progress` will cause error log lines to be written as `verbose` log lines.
+- `stderr-output` will cause error log lines to be written as `info` log lines (standard output). Requires version `2025.3`.
 
 To return to the default standard error log level, write the following message:
-```
+
+```text Return to the default standard error log level
 ##octopus[stderr-default]
 ```

src/pages/docs/deployments/custom-scripts/output-variables.md

@@ -97,7 +97,7 @@ let appInstanceName3 = Octopus.tryFindVariable "Octopus.Action[Determine App Ins
 <details data-group="using-variable-in-another-step">
 <summary>Python3</summary>
 
-```python Python3
+```python
 appInstanceName = get_octopusvariable("Octopus.Action[Determine App Instance Name].Output.AppInstanceName")
 ```
 
@@ -106,6 +106,7 @@ appInstanceName = get_octopusvariable("Octopus.Action[Determine App Instance Nam
 ## Service message
 
 The following service message can be written directly (substituting the properties with the relevant values) to standard output which will be parsed by the server and the values processed as an output variable. Note that the properties must be supplied as a base64 encoded UTF-8 string.
-```
+
+```text Write an output variable from standard output
 ##octopus[setVariable name='<Base64Encoded-VariableName>' value='<Base64Encoded-VariableValue>']
 ```

src/pages/docs/deployments/custom-scripts/scripts-in-packages/reference-files-within-a-package.md

@@ -52,7 +52,7 @@ Get-Content ".\subfolder\file.txt"
 <details data-group="deployments-custom-scripts-reference-files-within-package">
 <summary>C#</summary>
 
-```csharp C#
+```csharp
 // in pre-deploy, in post-deploy if custom installation directory has not been defined
 var extractPath = OctopusParameters["Octopus.Action.Package.InstallationDirectoryPath"];
 // if a custom installation directory has been defined

src/pages/docs/deployments/git/commit-to-git.md

@@ -81,7 +81,7 @@ For example, the following scripts write a release marker into the repository be
 <details data-group="deployments-git-commit-to-git-script">
 <summary>PowerShell</summary>
 
-```powershell PowerShell
+```powershell
 # Get the path to the cloned repository
 $repoPath = $OctopusParameters["Octopus.Calamari.Git.RepositoryPath"]
 
@@ -93,7 +93,7 @@ $repoPath = $OctopusParameters["Octopus.Calamari.Git.RepositoryPath"]
 <details data-group="deployments-git-commit-to-git-script">
 <summary>C#</summary>
 
-```csharp C#
+```csharp
 // Get the path to the cloned repository
 var repoPath = OctopusParameters["Octopus.Calamari.Git.RepositoryPath"];
 
@@ -105,7 +105,7 @@ System.IO.File.WriteAllText(System.IO.Path.Combine(repoPath, "release-marker.txt
 <details data-group="deployments-git-commit-to-git-script">
 <summary>Bash</summary>
 
-```bash Bash
+```bash
 # Get the path to the cloned repository
 repo_path=$(get_octopusvariable "Octopus.Calamari.Git.RepositoryPath")
 
@@ -117,7 +117,7 @@ echo "Released #{Octopus.Release.Number} to #{Octopus.Environment.Name}" > "$rep
 <details data-group="deployments-git-commit-to-git-script">
 <summary>Python</summary>
 
-```python Python
+```python
 # Get the path to the cloned repository
 repo_path = get_octopusvariable("Octopus.Calamari.Git.RepositoryPath")
 

src/pages/docs/infrastructure/deployment-targets/dynamic-infrastructure/new-octopustarget.mdx

@@ -61,7 +61,7 @@ Below is an example of creating an AWS ECS Cluster target with [account credenti
 <details data-group="account-credentials">
 <summary>PowerShell</summary>
 
-```powershell PowerShell
+```powershell
 $inputs = @"
 {
     "clusterName": "$($OctopusParameters["clusterName"])",
@@ -137,7 +137,7 @@ New-OctopusTarget -Name "$($OctopusParameters["target_name"])" -TargetId "aws-ec
 <details data-group="worker-credentials">
 <summary>Bash</summary>
 
-```bash Bash
+```bash
 read -r -d '' INPUTS <<EOT
 {
     "clusterName": "$(get_octopusvariable "clusterName")",

src/pages/docs/kubernetes/steps/kustomize.mdx

@@ -24,7 +24,7 @@ We list a few scenarios below to help you figure out what is the best setup for
 1. **Multiple overlays**  
    This is the recommended usage if you are already using Kustomize and just want Octopus to orchestrate the deployment.
    In this scenario, our recommendation is to use `.env` files with Octopus [variable substitution syntax](/docs/projects/variables/variable-substitutions), so we can replace secrets and any other data managed via Octopus variables. These `.env` files are then used by [secretGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_secretgenerator_) and/or [configMapGenerator](https://kubectl.docs.kubernetes.io/references/kustomize/builtins/#_configmapgenerator_).  
-   Everything else is defined in the `kustomization.yaml` files directly, and overlays should match the same environment structure defined in Octopus itself. 
+   Everything else is defined in the `kustomization.yaml` files directly, and overlays should match the same environment structure defined in Octopus itself.
 
 2. **Single overlay for Octopus**  
    In this scenario, you may define two overlays, one being for local use outside Octopus, so you can test your `yaml` files. The other overlay is used exclusively by Octopus.  
@@ -49,7 +49,7 @@ This field must be a path to a directory containing the `kustomization.yaml` fil
 During deployment, **Kustomize** reads the `kustomization.yaml` file located at this path to perform manifest yaml transforms.  
 The path is relative to the root of the git repository.
 When using overlays, ensure the path is to the overlay directory containing `kustomization.yaml` file.  
-Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this. 
+Also, remember that in Linux workers, the paths are case-sensitive, so it is always good practice to check this.
 
 ## Substitute Variables in Files
 
@@ -76,7 +76,7 @@ For example, if you add a container image reference for `nginx`:
 
 You will then be able to select the version of this container image at release creation time. You can use the referenced `nginx` container image in your `kustomization.yaml` file using the following syntax:
 
-```yaml
+```yaml Reference a container image package by version
 # ~/myApp/kustomization.yaml
 
 resources:
@@ -96,4 +96,5 @@ The "`#{Octopus.Action.Package[nginx].PackageVersion}`" Octostache expression wi
 
 - `Kustomize` was renamed to `Deploy with Kustomize`.
 - If you store your project configuration in a Git repository using the [Configuration as code feature](/docs/projects/version-control), you can source your Kustomize files from the same Git repository as your deployment process by selecting Project as the Git repository source. When creating a Release, the commit hash used for your deployment process will also be used to source the Kustomize files. You can learn more in [this blog post](https://octopus.com/blog/git-resources-in-deployments).
-:::
+
+:::

src/pages/docs/octopus-rest-api/examples/users-and-teams/add-azure-ad-to-users.mdx

@@ -22,8 +22,8 @@ Provide values for:
 - Octopus URL
 - Octopus API Key
 - A list of users, supplied from either:
-    - The path to a CSV file containing user records
-    - The Octopus Username, Azure email address and (optionally) Azure display name
+  - The path to a CSV file containing user records
+  - The Octopus Username, Azure email address and (optionally) Azure display name
 - (Optional) whether or not to update the Octopus user's email address
 - (Optional) whether or not to update the Octopus user's display name
 - (Optional) whether or not to continue to the next user if an error occurs
@@ -33,28 +33,30 @@ Provide values for:
 
 ### Add Microsoft Entra ID identities to single user
 
-```powershell PowerShell (REST API)
+```powershell Add an identity to a single user
 AddAzureADLogins -OctopusURL "https://your-octopus-url/" -OctopusAPIKey "API-YOUR-KEY" -OctopusUsername "OctoUser" -AzureEmailAddress "octouser@exampledomain.com" -AzureDisplayName "Octo User" -ContinueOnError $False -Force $False -WhatIf $False -DebugLogging $False
 ```
 
 ### Add Microsoft Entra ID identities for multiple users from CSV file
 
-```powershell PowerShell (REST API)
+```powershell Add identities to every user in a CSV file
 AddAzureADLogins -OctopusURL "https://your-octopus-url/" -OctopusAPIKey "API-YOUR-KEY" -Path "/path/to/user_azure_ad_logins.csv" -ContinueOnError $False -Force $False -WhatIf $False -DebugLogging $False
 ```
 
 ### Example CSV file
 
 An example of the expected CSV file format is shown below:
 
-```
+```text Expected CSV format
 OctopusUsername, AzureEmailAddress, AzureDisplayName
 OctoUser, octouser@exampledomain.com, Octo User 
 ```
+
 The first row should be the header row containing the following columns:
- - `OctopusUsername`
- - `AzureEmailAddress`
- - `AzureDisplayName`
+
+- `OctopusUsername`
+- `AzureEmailAddress`
+- `AzureDisplayName`
 
 ### Script