From f40de407142862fd8d724ce6492ee8aa26a21fe1 Mon Sep 17 00:00:00 2001
From: Oliver Salzburg <oliver.salzburg@adesso.de>
Date: Thu, 30 Jul 2026 15:13:22 +0200
Subject: [PATCH 1/3] Improve shell syntax highlighting

As is, there are several code blocks with lines prefixed with `$`, indicating to me that they want to mimic a shell session. These code blocks are marked with either `sh` or `bash` tags, to suggest syntax highlighting appropriate for such shell sessions.

This doesn't seem ideal, because command output is highlighted just as if it was another shell command.

Hugo uses the Chroma syntax highlighter, which provides a dedicated lexer specifically for such scenarios. This change makes use of that lexer to improve the formatting.

There were several cases where lines in these code blocks wanted to indicate comments using `#`, which indicates a comment in a shell script. However, because `#` commonly indicates the prompt of a root shell, such lines had to be adjusted to correctly reflect shell usage, where the comment would be entered on the prompt.

The type `console` was specifically chosen in favor over other tags (like `bash-session`), because the docsy theme specifically supports this language tag to improve the user experience on such code blocks. The copy-to-clipboard behavior will not copy command output, or the prompt character, in these cases.

Signed-off-by: Oliver Salzburg <oliver.salzburg@adesso.de>
---
 content/en/docs/installation/_index.md        |  4 +-
 content/en/docs/reference/_index.md           |  6 +-
 content/en/docs/security/_index.md            |  2 +-
 content/en/docs/usage/advanced/_index.md      | 68 +++++++++----------
 .../en/docs/usage/common-operations/_index.md | 42 ++++++------
 content/en/docs/usage/first-steps/_index.md   | 22 +++---
 .../en/docs/usage/identities/age/_index.md    |  4 +-
 .../usage/identities/amazon-aws-kms/_index.md |  2 +-
 .../docs/usage/identities/azure-kms/_index.md | 20 +++---
 .../usage/identities/config-file/_index.md    |  2 +-
 .../identities/google-cloud-kms/_index.md     | 24 +++----
 .../hashicorp-vault-openbao/_index.md         |  4 +-
 .../identities/huaweicloud-kms/_index.md      |  8 +--
 .../usage/identities/key-groups/_index.md     |  8 +--
 .../en/docs/usage/identities/pgp/_index.md    |  2 +-
 .../en/docs/usage/key-management/_index.md    | 16 ++---
 content/en/docs/usage/publishing/_index.md    |  2 +-
 17 files changed, 117 insertions(+), 119 deletions(-)

diff --git a/content/en/docs/installation/_index.md b/content/en/docs/installation/_index.md
index d060354..ab0f8a6 100644
--- a/content/en/docs/installation/_index.md
+++ b/content/en/docs/installation/_index.md
@@ -14,7 +14,7 @@ Binaries and packages of the latest stable release are available at
 For the adventurous, unstable features are available in the
 [main](https://github.com/getsops/sops/commits/main/) branch, which you can install from source:
 
-``` bash
+``` console
 $ mkdir -p $GOPATH/src/github.com/getsops/sops/
 $ git clone https://github.com/getsops/sops.git $GOPATH/src/github.com/getsops/sops/
 $ cd $GOPATH/src/github.com/getsops/sops/
@@ -25,7 +25,7 @@ $ make install
 
 If you don\'t have Go installed, set it up with:
 
-``` bash
+``` console
 $ {apt,yum,brew} install golang
 $ echo 'export GOPATH=~/go' >> ~/.bashrc
 $ source ~/.bashrc
diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md
index adee929..021f4f8 100644
--- a/content/en/docs/reference/_index.md
+++ b/content/en/docs/reference/_index.md
@@ -19,7 +19,7 @@ be decrypted in the same format. The easiest way to achieve this is to
 conserve the original file extension after encrypting a file. For
 example:
 
-``` sh
+``` console
 $ sops encrypt -i myfile.json
 $ sops decrypt myfile.json
 ```
@@ -28,7 +28,7 @@ If you want to change the extension of the file once encrypted, you need
 to provide `sops` with the `--input-type` flag upon decryption. For
 example:
 
-``` sh
+``` console
 $ sops encrypt myfile.json > myfile.json.enc
 
 $ sops decrypt --input-type json myfile.json.enc
@@ -37,7 +37,7 @@ $ sops decrypt --input-type json myfile.json.enc
 When operating on stdin, use the `--input-type` and `--output-type`
 flags as follows:
 
-``` sh
+``` console
 $ cat myfile.json | sops decrypt --input-type json --output-type json
 ```
 
diff --git a/content/en/docs/security/_index.md b/content/en/docs/security/_index.md
index 1199948..61d9323 100644
--- a/content/en/docs/security/_index.md
+++ b/content/en/docs/security/_index.md
@@ -112,7 +112,7 @@ encrypted PGP file: by referencing the pubkeys of each individual who
 has access to the file. It can easily be done by providing SOPS with a
 comma-separated list of public keys when creating a new file:
 
-``` sh
+``` console
 $ sops edit --pgp "E60892BB9BD89A69F759A1A0A3D652173B763E8F,84050F1D61AF7C230A12217687DF65059EF093D3,85D77543B3D624B63CEA9E6DBC17301B491B3F21" mynewfile.yaml
 ```
 
diff --git a/content/en/docs/usage/advanced/_index.md b/content/en/docs/usage/advanced/_index.md
index 144a7ac..6c22809 100644
--- a/content/en/docs/usage/advanced/_index.md
+++ b/content/en/docs/usage/advanced/_index.md
@@ -18,7 +18,7 @@ select the correct creation rule.
 
 The simplest way to decrypt data from stdin is as follows:
 
-``` sh
+``` console
 $ cat encrypted-data | sops decrypt > decrypted-data
 ```
 
@@ -31,7 +31,7 @@ To avoid this, you can either provide a filename with `--filename-override`,
 or explicitly control the input and output formats by passing
 `--input-type` and `--output-type` as appropriate:
 
-``` sh
+``` console
 $ cat encrypted-data | sops decrypt --filename-override filename.yaml > decrypted-data
 $ cat encrypted-data | sops decrypt --input-type yaml --output-type yaml > decrypted-data
 ```
@@ -45,7 +45,7 @@ look up the correct creation rule from `.sops.yaml`. Therefore, you must
 provide the `--filename-override` parameter which allows you to tell
 SOPS which filename to use to match creation rules:
 
-``` sh
+``` console
 $ echo 'foo: bar' | sops encrypt --filename-override path/filename.sops.yaml > encrypted-data
 ```
 
@@ -55,7 +55,7 @@ filename will also be used to determine the input and output store. As
 always, the input store type can be adjusted by passing `--input-type`,
 and the output store type by passing `--output-type`:
 
-``` sh
+``` console
 $ echo foo=bar | sops encrypt --filename-override path/filename.sops.yaml --input-type dotenv > encrypted-data
 ```
 
@@ -115,8 +115,8 @@ respectively. For example, if a program looks for credentials in its
 environment, `exec-env` can be used to ensure that the decrypted
 contents are available only to this process and never written to disk.
 
-``` sh
-# print secrets to stdout to confirm values
+``` console
+$ # print secrets to stdout to confirm values
 $ sops decrypt out.json
 {
         "database_password": "jf48t9wfw094gf4nhdf023r",
@@ -124,18 +124,18 @@ $ sops decrypt out.json
         "AWS_SECRET_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
 }
 
-# decrypt out.json and run a command
-# the command prints the environment variable and runs a script that uses it
+$ # decrypt out.json and run a command
+$ # the command prints the environment variable and runs a script that uses it
 $ sops exec-env out.json 'echo secret: $database_password; ./database-import'
 secret: jf48t9wfw094gf4nhdf023r
 
-# launch a shell with the secrets available in its environment
+$ # launch a shell with the secrets available in its environment
 $ sops exec-env out.json 'sh'
-sh-3.2# echo $database_password
+$ echo $database_password
 jf48t9wfw094gf4nhdf023r
 
-# the secret is not accessible anywhere else
-sh-3.2$ exit
+$ # the secret is not accessible anywhere else
+$ exit
 $ echo your password: $database_password
 your password:
 ```
@@ -154,9 +154,9 @@ the process is finished executing. `exec-file` behaves similar to
 will be substituted with the temporary file path (whether a FIFO or an
 actual file).
 
-``` sh
-# operating on the same file as before, but as a file this time
-$ sops exec-file out.json 'echo your temporary file: {}; cat {}'
+``` console
+% # operating on the same file as before, but as a file this time
+% sops exec-file out.json 'echo your temporary file: {}; cat {}'
 your temporary file: /tmp/.sops894650499/tmp-file
 {
         "database_password": "jf48t9wfw094gf4nhdf023r",
@@ -164,21 +164,21 @@ your temporary file: /tmp/.sops894650499/tmp-file
         "AWS_SECRET_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
 }
 
-# launch a shell with a variable TMPFILE pointing to the temporary file
-$ sops exec-file --no-fifo out.json 'TMPFILE={} sh'
-sh-3.2$ echo $TMPFILE
+% # launch a shell with a variable TMPFILE pointing to the temporary file
+% sops exec-file --no-fifo out.json 'TMPFILE={} sh'
+$ echo $TMPFILE
 /tmp/.sops506055069/tmp-file291138648
-sh-3.2$ cat $TMPFILE
+$ cat $TMPFILE
 {
         "database_password": "jf48t9wfw094gf4nhdf023r",
         "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
         "AWS_SECRET_KEY": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
 }
-sh-3.2$ ./program --config $TMPFILE
-sh-3.2$ exit
+$ ./program --config $TMPFILE
+$ exit
 
-# try to open the temporary file from earlier
-$ cat /tmp/.sops506055069/tmp-file291138648
+% # try to open the temporary file from earlier
+% cat /tmp/.sops506055069/tmp-file291138648
 cat: /tmp/.sops506055069/tmp-file291138648: No such file or directory
 ```
 
@@ -192,20 +192,20 @@ possible for added security.
 To overwrite the default file name (`tmp-file`) in `exec-file` use the
 `--filename <filename>` parameter.
 
-``` sh
-# the encrypted file can't be read by the current user
-$ cat out.json
+``` console
+% # the encrypted file can't be read by the current user
+% cat out.json
 cat: out.json: Permission denied
 
-# execute sops as root, decrypt secrets, then drop privileges
-$ sudo sops exec-env --user nobody out.json 'sh'
-sh-3.2$ echo $database_password
+% # execute sops as root, decrypt secrets, then drop privileges
+% sudo sops exec-env --user nobody out.json 'sh'
+$ echo $database_password
 jf48t9wfw094gf4nhdf023r
 
-# dropped privileges, still can't load the original file
-sh-3.2$ id
+$ # dropped privileges, still can't load the original file
+$ id
 uid=4294967294(nobody) gid=4294967294(nobody) groups=4294967294(nobody)
-sh-3.2$ cat out.json
+$ cat out.json
 cat: out.json: Permission denied
 ```
 
@@ -248,13 +248,13 @@ For example, to decrypt a file using both the local key service and the
 key service exposed on the unix socket located in `/tmp/sops.sock`, you
 can run:
 
-``` sh
+``` console
 $ sops decrypt --keyservice unix:///tmp/sops.sock file.yaml
 ```
 
 And if you only want to use the key service exposed on the unix socket
 located in `/tmp/sops.sock` and not the local key service, you can run:
 
-``` sh
+``` console
 $ sops decrypt --enable-local-keyservice=false --keyservice unix:///tmp/sops.sock file.yaml
 ```
diff --git a/content/en/docs/usage/common-operations/_index.md b/content/en/docs/usage/common-operations/_index.md
index 5486a03..0298350 100644
--- a/content/en/docs/usage/common-operations/_index.md
+++ b/content/en/docs/usage/common-operations/_index.md
@@ -23,7 +23,7 @@ result in an error.
 The command below creates a new file with a data key encrypted by KMS
 and PGP.
 
-``` sh
+``` console
 $ sops edit --kms "arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500" --pgp C9CAB0AF1165060DB58D6D6B2653B624D620786D /path/to/new/file.yaml
 ```
 
@@ -34,7 +34,7 @@ key. The path points to an existing cleartext file, so we give `sops`
 the flag `-e` to encrypt the file, and redirect the output to a
 destination file.
 
-``` sh
+``` console
 $ export SOPS_KMS_ARN="arn:aws:kms:us-west-2:927034868273:key/fe86dd69-4132-404c-ab86-4269956b4500"
 $ export SOPS_PGP_FP="C9CAB0AF1165060DB58D6D6B2653B624D620786D"
 $ sops encrypt /path/to/existing/file.yaml > /path/to/new/encrypted/file.yaml
@@ -42,7 +42,7 @@ $ sops encrypt /path/to/existing/file.yaml > /path/to/new/encrypted/file.yaml
 
 Decrypt the file with `-d`.
 
-``` sh
+``` console
 $ sops decrypt /path/to/new/encrypted/file.yaml
 ```
 
@@ -51,12 +51,12 @@ $ sops decrypt /path/to/new/encrypted/file.yaml
 Rather than redirecting the output of `-e` or `-d`, `sops` can replace
 the original file after encrypting or decrypting it.
 
-``` sh
-# file.yaml is in cleartext
+``` console
+$ # file.yaml is in cleartext
 $ sops encrypt -i /path/to/existing/file.yaml
-# file.yaml is now encrypted
+$ # file.yaml is now encrypted
 $ sops decrypt -i /path/to/existing/file.yaml
-# file.yaml is back in cleartext
+$ # file.yaml is back in cleartext
 ```
 
 ## Encrypting binary files
@@ -71,7 +71,7 @@ encrypted file larger than the cleartext one.
 
 In-place encryption/decryption also works on binary files.
 
-``` sh
+``` console
 $ dd if=/dev/urandom of=/tmp/somerandom bs=1024
 count=512
 512+0 records in
@@ -96,7 +96,7 @@ SOPS can extract a specific part of a YAML or JSON document, by provided
 the path in the `--extract` command line flag. This is useful to extract
 specific values, like keys, without needing an extra parser.
 
-``` sh
+``` console
 $ sops decrypt --extract '["app2"]["key"]' ~/git/svc/sops/example.yaml
 -----BEGIN RSA PRIVATE KEY-----
 MIIBPAIBAAJBAPTMNIyHuZtpLYc7VsHQtwOkWYobkUblmHWRmbXzlAX6K8tMf3Wf
@@ -113,7 +113,7 @@ The tree path syntax uses regular python dictionary syntax, without the
 variable name. Extract keys by naming them, and array elements by
 numbering them.
 
-``` sh
+``` console
 $ sops decrypt --extract '["an_array"][1]' ~/git/svc/sops/example.yaml
 secretuser2
 ```
@@ -124,7 +124,7 @@ SOPS can set a specific part of a YAML or JSON document, by providing
 the path and value in the `set` command. This is useful to set specific
 values, like keys, without needing an editor.
 
-``` sh
+``` console
 $ sops set ~/git/svc/sops/example.yaml '["app2"]["key"]' '"app2keystringvalue"'
 ```
 
@@ -132,24 +132,24 @@ The tree path syntax uses regular python dictionary syntax, without the
 variable name. Set to keys by naming them, and array elements by
 numbering them.
 
-``` sh
+``` console
 $ sops set ~/git/svc/sops/example.yaml '["an_array"][1]' '"secretuser2"'
 ```
 
 The value must be formatted as json.
 
-``` sh
+``` console
 $ sops set ~/git/svc/sops/example.yaml '["an_array"][1]' '{"uid1":null,"uid2":1000,"uid3":["bob"]}'
 ```
 
 You can also provide the value from a file or stdin:
 
-``` sh
-# Provide the value from a file
+``` console
+$ # Provide the value from a file
 $ echo '{"uid1":null,"uid2":1000,"uid3":["bob"]}' > /tmp/example-value
 $ sops set --value-file ~/git/svc/sops/example.yaml '["an_array"][1]' /tmp/example-value
 
-# Provide the value from stdin
+$ # Provide the value from stdin
 $ echo '{"uid1":null,"uid2":1000,"uid3":["bob"]}' | sops set --value-stdin ~/git/svc/sops/example.yaml '["an_array"][1]'
 ```
 
@@ -159,7 +159,7 @@ Symmetrically, SOPS can unset a specific part of a YAML or JSON document, by pro
 the path in the `unset` command. This is useful to unset specific values, like keys, without
 needing an editor.
 
-``` sh
+``` console
 $ sops unset ~/git/svc/sops/example.yaml '["app2"]["key"]'
 ```
 
@@ -167,7 +167,7 @@ The tree path syntax uses regular python dictionary syntax, without the
 variable name. Set to keys by naming them, and array elements by
 numbering them.
 
-``` sh
+``` console
 $ sops unset ~/git/svc/sops/example.yaml '["an_array"][1]'
 ```
 
@@ -190,7 +190,7 @@ Here we only care about YAML files. `sopsdiffer` is an arbitrary name
 that we map to a SOPS command in the git configuration file of the
 repository.
 
-``` sh
+``` console
 $ git config diff.sopsdiffer.textconv "sops decrypt"
 
 $ grep -A 1 sopsdiffer .git/config
@@ -234,7 +234,7 @@ A third method is to use the `--encrypted-regex` which will only encrypt
 values under keys that match the supplied regular expression. For
 example, this command:
 
-``` sh
+``` console
 $ sops encrypt --encrypted-regex '^(data|stringData)$' k8s-secrets.yaml
 ```
 
@@ -248,7 +248,7 @@ by using the `--unencrypted-regex` option, which will leave the values
 unencrypted of those keys that match the supplied regular expression.
 For example, this command:
 
-``` sh
+``` console
 $ sops encrypt --unencrypted-regex '^(description|metadata)$' k8s-secrets.yaml
 ```
 
diff --git a/content/en/docs/usage/first-steps/_index.md b/content/en/docs/usage/first-steps/_index.md
index a0eb5d9..d81b0de 100644
--- a/content/en/docs/usage/first-steps/_index.md
+++ b/content/en/docs/usage/first-steps/_index.md
@@ -15,8 +15,8 @@ console and export them, comma separated, in the **SOPS_KMS_ARN** env
 variable. It is recommended to use at least two master keys in different
 regions.
 
-``` bash
-export SOPS_KMS_ARN="arn:aws:kms:us-east-1:656532927350:key/920aff2e-c5f1-4040-943a-047fa387b27e,arn:aws:kms:ap-southeast-1:656532927350:key/9006a8aa-0fa6-4c14-930e-a2dfb916de1d"
+``` console
+$ export SOPS_KMS_ARN="arn:aws:kms:us-east-1:656532927350:key/920aff2e-c5f1-4040-943a-047fa387b27e,arn:aws:kms:ap-southeast-1:656532927350:key/9006a8aa-0fa6-4c14-930e-a2dfb916de1d"
 ```
 
 SOPS uses [aws-sdk-go-v2](https://github.com/aws/aws-sdk-go-v2) to
@@ -26,7 +26,7 @@ from the `~/.aws/credentials` file which can be created with the
 
 An example of the `~/.aws/credentials` file is shown below:
 
-``` sh
+``` console
 $ cat ~/.aws/credentials
 [default]
 aws_access_key_id = AKI.....
@@ -37,9 +37,9 @@ In addition to the `~/.aws/credentials` file, you can also use the
 `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables to
 specify your credentials:
 
-``` bash
-export AWS_ACCESS_KEY_ID="AKI......"
-export AWS_SECRET_ACCESS_KEY="mw......"
+``` console
+$ export AWS_ACCESS_KEY_ID="AKI......"
+$ export AWS_SECRET_ACCESS_KEY="mw......"
 ```
 
 For more information and additional environment variables, see
@@ -49,8 +49,8 @@ credentials](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure
 If you want to use PGP, export the fingerprints of the public keys,
 comma separated, in the **SOPS_PGP_FP** env variable.
 
-``` bash
-export SOPS_PGP_FP="85D77543B3D624B63CEA9E6DBC17301B491B3F21,E60892BB9BD89A69F759A1A0A3D652173B763E8F"
+``` console
+$ export SOPS_PGP_FP="85D77543B3D624B63CEA9E6DBC17301B491B3F21,E60892BB9BD89A69F759A1A0A3D652173B763E8F"
 ```
 
 > 📝 **Note**
@@ -61,7 +61,7 @@ Then simply call `sops edit` with a file path as argument. It will
 handle the encryption/decryption transparently and open the cleartext
 file in an editor
 
-``` sh
+``` console
 $ sops edit mynewtestfile.yaml
 mynewtestfile.yaml doesn't exist, creating it.
 please wait while an encryption key is being generated and stored in a secure fashion
@@ -116,7 +116,7 @@ you will be able to access your data.
 
 To decrypt a file in a `cat` fashion, use the `-d` flag:
 
-``` sh
+``` console
 $ sops decrypt mynewtestfile.yaml
 ```
 
@@ -126,7 +126,7 @@ necessary permissions on KMS keys.
 
 Given that, the only command a SOPS user needs is:
 
-``` sh
+``` console
 $ sops edit <file>
 ```
 
diff --git a/content/en/docs/usage/identities/age/_index.md b/content/en/docs/usage/identities/age/_index.md
index f4701b2..2336d04 100644
--- a/content/en/docs/usage/identities/age/_index.md
+++ b/content/en/docs/usage/identities/age/_index.md
@@ -14,7 +14,7 @@ You can encrypt a file for one or more age recipients (comma separated)
 using the `--age` option or the **SOPS_AGE_RECIPIENTS** environment
 variable:
 
-``` sh
+``` console
 $ sops encrypt --age age1yt3tfqlfrwdwx0z0ynwplcr6qxcxfaqycuprpmy89nr83ltx74tqdpszlw test.yaml > test.enc.yaml
 ```
 
@@ -76,7 +76,7 @@ creation_rules:
 
 It is also possible to use `updatekeys`, when adding or removing age recipients. For example:
 
-``` sh
+``` console
 $ sops updatekeys secret.enc.yaml
 2022/02/09 16:32:02 Syncing keys for file /iac/solution1/secret.enc.yaml
 The following changes will be made to the file's groups:
diff --git a/content/en/docs/usage/identities/amazon-aws-kms/_index.md b/content/en/docs/usage/identities/amazon-aws-kms/_index.md
index 1bae7bc..0f1af0a 100644
--- a/content/en/docs/usage/identities/amazon-aws-kms/_index.md
+++ b/content/en/docs/usage/identities/amazon-aws-kms/_index.md
@@ -89,7 +89,7 @@ to refine the access control of a given KMS master key.
 When creating a new file, you can specify the encryption context in the
 `--encryption-context` flag by comma separated list of key-value pairs:
 
-``` sh
+``` console
 $ sops edit --encryption-context Environment:production,Role:web-server test.dev.yaml
 ```
 
diff --git a/content/en/docs/usage/identities/azure-kms/_index.md b/content/en/docs/usage/identities/azure-kms/_index.md
index e54bc68..d2c3386 100644
--- a/content/en/docs/usage/identities/azure-kms/_index.md
+++ b/content/en/docs/usage/identities/azure-kms/_index.md
@@ -28,7 +28,7 @@ which tries several authentication methods, in this order:
 For example, you can use a Service Principal with the following
 environment variables:
 
-``` bash
+```
 AZURE_TENANT_ID
 AZURE_CLIENT_ID
 AZURE_CLIENT_SECRET
@@ -36,7 +36,7 @@ AZURE_CLIENT_SECRET
 
 You can create a Service Principal using the CLI like this:
 
-``` sh
+``` console
 $ az ad sp create-for-rbac -n my-keyvault-sp
 
 {
@@ -68,17 +68,17 @@ https://${VAULT_URL}/keys/${KEY_NAME}/
 To create a Key Vault and assign your service principal permissions on
 it from the commandline:
 
-``` sh
-# Create a resource group if you do not have one:
+``` console
+$ # Create a resource group if you do not have one:
 $ az group create --name sops-rg --location westeurope
-# Key Vault names are globally unique, so generate one:
+$ # Key Vault names are globally unique, so generate one:
 $ keyvault_name=sops-$(uuidgen | tr -d - | head -c 16)
-# Create a Vault, a key, and give the service principal access:
+$ # Create a Vault, a key, and give the service principal access:
 $ az keyvault create --name $keyvault_name --resource-group sops-rg --location westeurope
 $ az keyvault key create --name sops-key --vault-name $keyvault_name --protection software --ops encrypt decrypt
 $ az keyvault set-policy --name $keyvault_name --resource-group sops-rg --spn $AZURE_CLIENT_ID \
     --key-permissions get encrypt decrypt
-# Read the key id:
+$ # Read the key id:
 $ az keyvault key show --name sops-key --vault-name $keyvault_name --query key.kid
 
 https://sops.vault.azure.net/keys/sops-key/some-string
@@ -92,18 +92,18 @@ https://sops.vault.azure.net/keys/sops-key/some-string
 
 Now you can encrypt a file using:
 
-``` sh
+``` console
 $ sops encrypt --azure-kv https://sops.vault.azure.net/keys/sops-key/some-string test.yaml > test.enc.yaml
 ```
 
 or, without the version:
 
-``` sh
+``` console
 $ sops encrypt --azure-kv https://sops.vault.azure.net/keys/sops-key/ test.yaml > test.enc.yaml
 ```
 
 And decrypt it using:
 
-``` sh
+``` console
 $ sops decrypt test.enc.yaml
 ```
diff --git a/content/en/docs/usage/identities/config-file/_index.md b/content/en/docs/usage/identities/config-file/_index.md
index 1a1460f..293defe 100644
--- a/content/en/docs/usage/identities/config-file/_index.md
+++ b/content/en/docs/usage/identities/config-file/_index.md
@@ -101,7 +101,7 @@ creation_rules:
 
 Creating a new file with the right keys is now as simple as
 
-``` sh
+``` console
 $ sops edit <newfile>.prod.yaml
 ```
 
diff --git a/content/en/docs/usage/identities/google-cloud-kms/_index.md b/content/en/docs/usage/identities/google-cloud-kms/_index.md
index 37f0451..d5dac71 100644
--- a/content/en/docs/usage/identities/google-cloud-kms/_index.md
+++ b/content/en/docs/usage/identities/google-cloud-kms/_index.md
@@ -13,32 +13,32 @@ the use of access token.
 
 Using Application Default Credentials you can authorize by doing this:
 
-``` sh
+``` console
 $ gcloud auth login
 ```
 
 you can enable application default credentials using the sdk:
 
-``` sh
+``` console
 $ gcloud auth application-default login
 ```
 
 Using OAauth tokens you can authorize by doing this:
 
-``` sh
+``` console
 $ export GOOGLE_OAUTH_ACCESS_TOKEN=<your access token>
 ```
 
 Or if you are logged in you can authorize by generating an access token:
 
-``` sh
+``` console
 $ export GOOGLE_OAUTH_ACCESS_TOKEN="$(gcloud auth print-access-token)"
 ```
 
 By default, SOPS uses the gRPC client to communicate with GCP KMS. You can optionally
 switch to the REST client by setting the `SOPS_GCP_KMS_CLIENT_TYPE` environment variable:
 
-``` sh
+``` console
 $ export SOPS_GCP_KMS_CLIENT_TYPE=rest  # Use REST client
 $ export SOPS_GCP_KMS_CLIENT_TYPE=grpc  # Use gRPC client (default)
 ```
@@ -47,11 +47,11 @@ For sovereign cloud environments that expose a GCP-compatible KMS API at a
 non-standard endpoint (e.g. S3NS/Thales TPC: `cloudkms.s3nsapis.fr`),
 you can override the endpoint or the universe domain:
 
-``` sh
-# Override the KMS endpoint directly
+``` console
+$ # Override the KMS endpoint directly
 $ export SOPS_GCP_KMS_ENDPOINT=cloudkms.example.com:443
 
-# Or derive the endpoint from the universe domain (cloudkms.<domain>:443)
+$ # Or derive the endpoint from the universe domain (cloudkms.<domain>:443)
 $ export SOPS_GCP_KMS_UNIVERSE_DOMAIN=example.com
 ```
 
@@ -63,24 +63,22 @@ Encrypting/decrypting with GCP KMS requires a KMS ResourceID. You can
 use the cloud console the get the ResourceID or you can create one using
 the gcloud sdk:
 
-``` sh
+``` console
 $ gcloud kms keyrings create sops --location global
 $ gcloud kms keys create sops-key --location global --keyring sops --purpose encryption
 $ gcloud kms keys list --location global --keyring sops
-
-# you should see
 NAME                                                                   PURPOSE          PRIMARY_STATE
 projects/my-project/locations/global/keyRings/sops/cryptoKeys/sops-key ENCRYPT_DECRYPT  ENABLED
 ```
 
 Now you can encrypt a file using:
 
-``` sh
+``` console
 $ sops encrypt --gcp-kms projects/my-project/locations/global/keyRings/sops/cryptoKeys/sops-key test.yaml > test.enc.yaml
 ```
 
 And decrypt it using:
 
-``` sh
+``` console
 $ sops decrypt test.enc.yaml
 ```
diff --git a/content/en/docs/usage/identities/hashicorp-vault-openbao/_index.md b/content/en/docs/usage/identities/hashicorp-vault-openbao/_index.md
index 2852a04..5556116 100644
--- a/content/en/docs/usage/identities/hashicorp-vault-openbao/_index.md
+++ b/content/en/docs/usage/identities/hashicorp-vault-openbao/_index.md
@@ -12,11 +12,11 @@ instance of Vault, refer to Hashicorp\'s official documentation.
 
 To easily deploy Vault locally: (DO NOT DO THIS FOR PRODUCTION!!!)
 
-``` sh
+``` console
 $ docker run -d -p8200:8200 vault:1.2.0 server -dev -dev-root-token-id=toor
 ```
 
-``` sh
+``` console
 $ # Substitute this with the address Vault is running on
 $ export VAULT_ADDR=http://127.0.0.1:8200 
 
diff --git a/content/en/docs/usage/identities/huaweicloud-kms/_index.md b/content/en/docs/usage/identities/huaweicloud-kms/_index.md
index 141774a..fdfdd10 100644
--- a/content/en/docs/usage/identities/huaweicloud-kms/_index.md
+++ b/content/en/docs/usage/identities/huaweicloud-kms/_index.md
@@ -24,7 +24,7 @@ export HUAWEICLOUD_SDK_PROJECT_ID="your-project-id"
 
 Alternatively, you can create a credentials file at `~/.huaweicloud/credentials`:
 
-``` sh
+``` console
 $ cat ~/.huaweicloud/credentials
 [default]
 ak = your-access-key
@@ -41,20 +41,20 @@ the HuaweiCloud API. The key ID format is `region:key-uuid` where:
 
 Now you can encrypt a file using:
 
-``` sh
+``` console
 $ sops encrypt --hckms tr-west-1:abc12345-6789-0123-4567-890123456789 test.yaml > test.enc.yaml
 ```
 
 Or using the environment variable:
 
-``` sh
+``` console
 $ export SOPS_HUAWEICLOUD_KMS_IDS="tr-west-1:abc12345-6789-0123-4567-890123456789"
 $ sops encrypt test.yaml > test.enc.yaml
 ```
 
 And decrypt it using:
 
-``` sh
+``` console
 $ sops decrypt test.enc.yaml
 ```
 
diff --git a/content/en/docs/usage/identities/key-groups/_index.md b/content/en/docs/usage/identities/key-groups/_index.md
index 4b51300..a2cb858 100644
--- a/content/en/docs/usage/identities/key-groups/_index.md
+++ b/content/en/docs/usage/identities/key-groups/_index.md
@@ -34,14 +34,14 @@ Management of key groups is done with the `sops groups` command.
 For example, you can add a new key group with 3 PGP keys and 3 KMS keys
 to the file `my_file.yaml`:
 
-``` sh
+``` console
 $ sops groups add --file my_file.yaml --pgp fingerprint1 --pgp fingerprint2 --pgp fingerprint3 --kms arn1 --kms arn2 --kms arn3
 ```
 
 Or you can delete the 1st group (group number 0, as groups are
 zero-indexed) from `my_file.yaml`:
 
-``` sh
+``` console
 $ sops groups delete --file my_file.yaml 0
 ```
 
@@ -84,7 +84,7 @@ with the master keys found in each group.
 
 For example:
 
-``` sh
+``` console
 $ sops edit --shamir-secret-sharing-threshold 2 example.json
 ```
 
@@ -126,6 +126,6 @@ will require master keys from two of the three different key groups in
 order to decrypt the file. You can then decrypt the file the same way as
 with any other SOPS file:
 
-``` sh
+``` console
 $ sops decrypt example.json
 ```
diff --git a/content/en/docs/usage/identities/pgp/_index.md b/content/en/docs/usage/identities/pgp/_index.md
index f2adae6..587dfa6 100644
--- a/content/en/docs/usage/identities/pgp/_index.md
+++ b/content/en/docs/usage/identities/pgp/_index.md
@@ -9,7 +9,7 @@ description: You can use PGP / GnuPG to encrypt data.
 If you want to test **SOPS** without having to do a bunch of setup, you
 can use the example files and pgp key provided with the repository:
 
-``` sh
+``` console
 $ git clone https://github.com/getsops/sops.git
 $ cd sops
 $ gpg --import pgp/sops_functional_tests_key.asc
diff --git a/content/en/docs/usage/key-management/_index.md b/content/en/docs/usage/key-management/_index.md
index fbb7b81..bff1278 100644
--- a/content/en/docs/usage/key-management/_index.md
+++ b/content/en/docs/usage/key-management/_index.md
@@ -38,7 +38,7 @@ creation_rules:
         FBC7B9E2A4F9289AC0C1D4843D16CEE4A27381B4
 ```
 
-``` sh
+``` console
 $ sops updatekeys test.enc.yaml
 ```
 
@@ -57,11 +57,11 @@ creating new files.
 
 Use `updatekeys` if you want to add a key without rotating the data key.
 
-``` sh
-# add a new pgp key to the file and rotate the data key
+``` console
+$ # add a new pgp key to the file and rotate the data key
 $ sops rotate -i --add-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
 
-# remove a pgp key from the file and rotate the data key
+$ # remove a pgp key from the file and rotate the data key
 $ sops rotate -i --rm-pgp 85D77543B3D624B63CEA9E6DBC17301B491B3F21 example.yaml
 ```
 
@@ -107,7 +107,7 @@ in the file.
 Add the `-i` option to write the rotated file back, instead of printing
 it to stdout.
 
-``` sh
+``` console
 $ sops rotate example.yaml
 ```
 
@@ -115,9 +115,9 @@ $ sops rotate example.yaml
 
 First, remove the key from the key group in `.sops.yaml`, then run the following for each sops-encrypted file (only `secret.sops.yaml` in this example):
 
-``` sh
-sops updatekeys secret.sops.yaml
-sops rotate --in-place secret.sops.yaml
+``` console
+$ sops updatekeys secret.sops.yaml
+$ sops rotate --in-place secret.sops.yaml
 ```
 
 Commit and push the updated file.
diff --git a/content/en/docs/usage/publishing/_index.md b/content/en/docs/usage/publishing/_index.md
index 10f3859..9df4f38 100644
--- a/content/en/docs/usage/publishing/_index.md
+++ b/content/en/docs/usage/publishing/_index.md
@@ -69,7 +69,7 @@ same data as the source file, it will be skipped.
 Below is an example of publishing to Vault (using token auth with a
 local dev instance of Vault).
 
-``` sh
+``` console
 $ export VAULT_TOKEN=...
 $ export VAULT_ADDR='http://127.0.0.1:8200'
 $ sops decrypt vault/test.yaml

From 5dc6b4afe554e59ebd1adeaf9c40d10a6937baea Mon Sep 17 00:00:00 2001
From: "Oliver Salzburg (adesso)"
 <112879907+adesso-os@users.noreply.github.com>
Date: Mon, 3 Aug 2026 12:32:24 +0200
Subject: [PATCH 2/3] Update
 content/en/docs/usage/identities/azure-kms/_index.md

Co-authored-by: Felix Fontein <felix@fontein.de>
Signed-off-by: Oliver Salzburg (adesso) <112879907+adesso-os@users.noreply.github.com>
---
 content/en/docs/usage/identities/azure-kms/_index.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/content/en/docs/usage/identities/azure-kms/_index.md b/content/en/docs/usage/identities/azure-kms/_index.md
index d2c3386..fac2439 100644
--- a/content/en/docs/usage/identities/azure-kms/_index.md
+++ b/content/en/docs/usage/identities/azure-kms/_index.md
@@ -76,8 +76,7 @@ $ keyvault_name=sops-$(uuidgen | tr -d - | head -c 16)
 $ # Create a Vault, a key, and give the service principal access:
 $ az keyvault create --name $keyvault_name --resource-group sops-rg --location westeurope
 $ az keyvault key create --name sops-key --vault-name $keyvault_name --protection software --ops encrypt decrypt
-$ az keyvault set-policy --name $keyvault_name --resource-group sops-rg --spn $AZURE_CLIENT_ID \
-    --key-permissions get encrypt decrypt
+$ az keyvault set-policy --name $keyvault_name --resource-group sops-rg --spn $AZURE_CLIENT_ID --key-permissions get encrypt decrypt
 $ # Read the key id:
 $ az keyvault key show --name sops-key --vault-name $keyvault_name --query key.kid
 

From a5fb3438e887bca0aa09c94de893e71d6db9fcb7 Mon Sep 17 00:00:00 2001
From: "Oliver Salzburg (adesso)"
 <112879907+adesso-os@users.noreply.github.com>
Date: Mon, 3 Aug 2026 12:32:46 +0200
Subject: [PATCH 3/3] Update
 content/en/docs/usage/identities/azure-kms/_index.md

Co-authored-by: Felix Fontein <felix@fontein.de>
Signed-off-by: Oliver Salzburg (adesso) <112879907+adesso-os@users.noreply.github.com>
---
 content/en/docs/usage/identities/azure-kms/_index.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/content/en/docs/usage/identities/azure-kms/_index.md b/content/en/docs/usage/identities/azure-kms/_index.md
index fac2439..b611e18 100644
--- a/content/en/docs/usage/identities/azure-kms/_index.md
+++ b/content/en/docs/usage/identities/azure-kms/_index.md
@@ -28,11 +28,9 @@ which tries several authentication methods, in this order:
 For example, you can use a Service Principal with the following
 environment variables:
 
-```
-AZURE_TENANT_ID
-AZURE_CLIENT_ID
-AZURE_CLIENT_SECRET
-```
+* `AZURE_TENANT_ID`,
+* `AZURE_CLIENT_ID`,
+* `AZURE_CLIENT_SECRET`.
 
 You can create a Service Principal using the CLI like this: