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>

Author: adesso-os

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

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
 ```
 

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
 ```
 

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,27 +115,27 @@ 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",
         "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
         "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,31 +154,31 @@ 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",
         "AWS_ACCESS_KEY_ID": "AKIAIOSFODNN7EXAMPLE",
         "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
 ```

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,15 +34,15 @@ 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
 ```
 
 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,32 +124,32 @@ 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"'
 ```
 
 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,15 +159,15 @@ 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"]'
 ```
 
 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
 ```