Update code blocks and add guidelines on usage to style guide (#74)

I've attempted to fix up some code blocks. Whatever was obviously a terminal (ehm, console) session I've updated to use `console`. Turns out `terminal` isn't a valid lexer, and just does no highlighting. I've changed some types to `bash` or `console` a bit depending on the contents of the code block, but I have not tried to fix everything.

I've added a section about code blocks to the style guide, which we can try to follow when updating existing or adding new docs.

Author: msimberg

docs/access/mfa.md

@@ -50,8 +50,8 @@ Before starting, ensure that the following pre-requisites are satisfied
 
 !!! warning
     If you try to SSH to CSCS systems without setting up MFA, you will be prompted with permission denied error, for example:
-    ```
-    > ssh ela.cscs.ch
+    ```console
+    $ ssh ela.cscs.ch
     [email protected]: Permission denied (publickey).
     Connection closed by UNKNOWN port 65535
     ```

docs/clusters/clariden.md

@@ -84,8 +84,8 @@ See the SLURM documentation for instructions on how to run jobs on the [Grace-Ho
 
 ??? example "how to check the number of nodes on the system"
     You can check the size of the system by running the following command in the terminal:
-    ```terminal
-    > sinfo --format "| %20R | %10D | %10s | %10l | %10A |"
+    ```console
+    $ sinfo --format "| %20R | %10D | %10s | %10l | %10A |"
     | PARTITION            | NODES      | JOB_SIZE   | TIMELIMIT  | NODES(A/I) |
     | debug                | 32         | 1-2        | 30:00      | 3/29       |
     | normal               | 1266       | 1-infinite | 1-00:00:00 | 812/371    |

docs/clusters/santis.md

@@ -98,8 +98,8 @@ See the SLURM documentation for instructions on how to run jobs on the [Grace-Ho
 
 ??? example "how to check the number of nodes on the system"
     You can check the size of the system by running the following command in the terminal:
-    ```terminal
-    > sinfo --format "| %20R | %10D | %10s | %10l | %10A |"
+    ```console
+    $ sinfo --format "| %20R | %10D | %10s | %10l | %10A |"
     | PARTITION            | NODES      | JOB_SIZE   | TIMELIMIT  | NODES(A/I) |
     | debug                | 32         | 1-2        | 30:00      | 3/29       |
     | normal               | 1266       | 1-infinite | 1-00:00:00 | 812/371    |

docs/contributing/index.md

@@ -13,20 +13,20 @@ We use the GitHub fork and pull request model for development:
 Clone your fork repository on your PC/laptop:
 ```bash
 # clone your fork of the repository
-> git clone [email protected]:${githubusername}/cscs-docs.git
-> cd cscs-docs
-> git switch -c 'fix/ssh-alias'
+git clone [email protected]:${githubusername}/cscs-docs.git
+cd cscs-docs
+git switch -c 'fix/ssh-alias'
 # ... make your edits ...
 # add and commit your changes
-> git add <files>
-> git commit -m 'update the ssh docs with aliases for all user lab vclusters'
-> git push origin 'fix/ssh-alias'
+git add <files>
+git commit -m 'update the ssh docs with aliases for all user lab vclusters'
+git push origin 'fix/ssh-alias'
 ```
 Then navigate to GitHub, and create a pull request.
 
 The `serve` script in the root path of the repository can be used to view the docs locally:`
-```
-> ./serve
+```bash
+./serve
 ...
 INFO    -  [08:33:34] Serving on http://127.0.0.1:8000/
 ```
@@ -228,3 +228,56 @@ They stand out better from the main text, and can be collapsed by default if nee
     This note is collapsed, because it uses `???`.
 
 If an admonition is collapsed by default, it should have a title.
+
+### Code blocks
+
+Use [code blocks](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/) when you want to display monospace text in a programming language, terminal output, configuration files etc.
+The documentation uses [pygments](https://pygments.org) for highlighting.
+See [list of available lexers](https://pygments.org/docs/lexers/#) for the languages that you can use for code blocks.
+
+Use [`console`](https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer) for interactive sessions with prompt-output pairs:
+
+=== "Markdown"
+
+    ````markdown
+    ```console title="Hello, world!"
+    $ echo "Hello, world!"
+    Hello, world!
+    ```
+    ````
+
+=== "Rendered"
+
+    ```console title="Hello, world!"
+    $ echo "Hello, world!"
+    Hello, world!
+    ```
+
+!!! warning
+    `terminal` is not a valid lexer, but MkDocs or pygments will not warn about using it as a language.
+    The text will be rendered without highlighting.
+
+!!! warning
+    Use `$` as the prompt character, optionally preceded by text.
+    `>` as the prompt character will not be highlighted correctly.
+
+Note the use of `title=...`, which will give the code block a heading.
+
+!!! tip
+    Include a title whenever possible to describe what the code block does or is.
+
+If you want to display commands without output that can easily be copied, use `bash` as the language:
+
+=== "Markdown"
+
+    ````markdown
+    ```bash title="Hello, world!"
+    echo "Hello, world!"
+    ```
+    ````
+
+=== "Rendered"
+
+    ```bash title="Hello, world!"
+    echo "Hello, world!"
+    ```

docs/guides/gb2025.md

@@ -42,12 +42,12 @@ This confines system processes and operations to the first core of each of the f
 
 The consequence of this setting is that only 71 cores per socket can be requested by an application (for a total of 284 cores instead of 288 cores per node).
 
-!!! warning "Unable to allocate resources: Requested node configuration is not availabl"
+!!! warning "Unable to allocate resources: Requested node configuration is not available"
     If you try to use all 72 cores on each socket, SLURM will give a hard error, because only 71 are available:
 
-    ```
+    ```console
     # try to run 4 ranks per node, with 72 cores each
-    > srun -n4 -N1 -c72 --reservation=reshuffling ./build/affinity.mpi
+    $ srun -n4 -N1 -c72 --reservation=reshuffling ./build/affinity.mpi
     srun: error: Unable to allocate resources: Requested node configuration is not available
     ```
 

docs/guides/terminal.md

@@ -14,7 +14,7 @@ At CSCS the vast majority of users stick with the default `bash`: at the time of
 
     Run the following command after logging in:
 
-    ```terminal
+    ```console
     $ getent passwd | grep $USER
     bcumming:*:22008:1000:Benjamin Cumming, CSCS:/users/bcumming:/usr/local/bin/bash
     ```

docs/software/container-engine.md

@@ -50,13 +50,13 @@ Since the `ubuntu.toml` file is located in the [EDF search path][ref-ce-edf-sear
     The above terminal snippet demonstrates how to launch a containerized environment using Slurm with the `--environment` option.
     Click on the :fontawesome-solid-circle-plus: icon for information on each command.
 
-    ```bash
-    daint-ln002 > srun --environment=ubuntu --pty bash   # (1)
+    ```console
+    [daint-ln002]$ srun --environment=ubuntu --pty bash   # (1)
 
-    nid005333 > pwd                                    # (2)
+    [nid005333]$ pwd                                    # (2)
     /capstor/scratch/cscs/<username>
 
-    nid005333 > cat /etc/os-release                    # (3)
+    [nid005333]$ cat /etc/os-release                    # (3)
     PRETTY_NAME="Ubuntu 24.04 LTS"
     NAME="Ubuntu"
     VERSION_ID="24.04"
@@ -71,8 +71,8 @@ Since the `ubuntu.toml` file is located in the [EDF search path][ref-ce-edf-sear
     UBUNTU_CODENAME=noble
     LOGO=ubuntu-logo
 
-    nid005333 > exit                                  # (4)
-    daint-ln002 >
+    [nid005333]$ exit                                  # (4)
+    [daint-ln002]$
     ```
 
     1.  Starting an interactive shell session within the Ubuntu 24.04 container deployed on a compute node using `srun --environment=ubuntu --pty bash`.

docs/software/devtools/linaro-ddt.md

@@ -18,7 +18,7 @@ The following guide will walk through the steps required to build and debug an a
 Once the uenv is loaded and activated, the program to debug must be compiled with the `-g` (for CPU) and `-G` (for GPU) debugging flags.
 For example, we can build a CUDA test with a user environment:
 
-```terminal
+```bash
 uenv start prgenv-gnu:24.11:v1 --view=default
 nvcc -c -arch=sm_90 -g -G test_gpu.cu
 mpicxx -g test_cpu.cpp test_gpu.o -o myexe
@@ -41,13 +41,13 @@ To use the DDT client with uenv, it must be launched in `Manual Launch` mode
 
     Log into the system and launch with the `srun` command:
 
-    ```terminal
+    ```console
     # start a session with both the PE used to build your application
     # and the linaro-forge uenv mounted
-    > uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default
-    > source /user-tools/activate
+    $ uenv start prgenv-gnu/24.11:v1,linaro-forge/24.1.1:v1 --view=prgenv-gnu:default
+    $ source /user-tools/activate
 
-    > srun -N1 -n4 -t15 -pdebug ./cuda_visible_devices.sh   ddt-client   ./myexe
+    $ srun -N1 -n4 -t15 -pdebug ./cuda_visible_devices.sh   ddt-client   ./myexe
     ```
 
 ### Start debugging

docs/software/devtools/linaro-forge.md

@@ -18,12 +18,12 @@ The Linaro uenv is named `linaro-forge`, and the available versions can be deter
 
 !!! example "finding available linaro-forge versions"
 
-    ```
-    > uenv image find linaro-forge
+    ```console
+    $ uenv image find linaro-forge
     uenv                    arch   system  id                size(MB)  date
     linaro-forge/24.1.1:v1  gh200  daint   e0e79f5c3e6a8ee0  365       2025-02-12
 
-    > uenv image pull linaro-forge/24.1.1:v1
+    $ uenv image pull linaro-forge/24.1.1:v1
     pulling e0e79f5c3e6a8ee0 100.00% --- 365/365 (0.00 MB/s)
     ```
 
@@ -50,10 +50,10 @@ Version: 24.1.1
 !!! note
     The `linaro-forge` uenv is always mounted at the `/user-tools` mount point, and a script `/user-tools/activate` is provided to load both ddt and map into your environment, without needing to use a view.
 
-    ```bash
-    > uenv start linaro-forge/14.1.1
-    > source /user-tools/activate
-    > ddt --version
+    ```console
+    $ uenv start linaro-forge/14.1.1
+    $ source /user-tools/activate
+    $ ddt --version
     Linaro DDT Part of Linaro Forge.
     Copyright (c) 2023-2024 Linaro Limited. All rights reserved.
     Version: 24.1.1

docs/software/prgenv/prgenv-gnu.md

@@ -81,22 +81,22 @@ There are three ways to access the software provided by prgenv-gnu, once it has
     The simplest way to get started is to use the `default` file system view, which automatically loads all of the packages when the uenv is started.
 
     !!! example "test mpi compilers and python provided by prgenv-gnu/24.11"
-        ```bash
+        ```console
         # start using the default view
-        > uenv start --view=default prgenv-gnu/24.11:v1
+        $ uenv start --view=default prgenv-gnu/24.11:v1
 
         # the python executable provided by the uenv is the default, and is a recent version
-        > which python
+        $ which python
         /user-environment/env/default/bin/python
-        > python --version 
+        $ python --version 
         Python 3.12.5
 
         # the mpi compiler wrappers are also available
-        > which mpicc
+        $ which mpicc
         /user-environment/env/default/bin/mpicc
-        > mpicc --version
+        $ mpicc --version
         gcc (Spack GCC) 13.3.0
-        > gcc --version # the compiler wrapper uses the gcc provided by the uenv
+        $ gcc --version # the compiler wrapper uses the gcc provided by the uenv
         gcc (Spack GCC) 13.3.0
         ```
 
@@ -106,9 +106,9 @@ There are three ways to access the software provided by prgenv-gnu, once it has
     No modules are loaded when a uenv starts, and have to be loaded individually using `module load`.
 
     !!! example "starting prgenv-gnu and listing the provided modules"
-        ```bash
-        > uenv start prgenv-gnu/24.11:v1 --view=modules
-        > module avail
+        ```console
+        $ uenv start prgenv-gnu/24.11:v1 --view=modules
+        $ module avail
             ---------------------------- /user-environment/modules ----------------------------
            aws-ofi-nccl/git.v1.9.2-aws_1.9.2    lua/5.4.6
            boost/1.86.0                         lz4/1.10.0