merge

Author: RMeli

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

docs/software/prgenv/prgenv-nvfortran.md

@@ -92,9 +92,9 @@ uenv image find prgenv-nvfortran/24.11:v1
 
     The modules view will start the uenv, and make a set of modules available:
 
-    ```
-    > uenv start prgenv-nvfortran/24.11:v1 --view=nvfort,modules
-    > module avail
+    ```console
+    $ uenv start prgenv-nvfortran/24.11:v1 --view=nvfort,modules
+    $ module avail
     ---------------------------- /user-environment/modules ----------------------------
        aws-ofi-nccl/master    libtree/3.1.1           ninja/1.12.1
        cmake/3.30.5           lua/5.4.6               nvhpc/24.11

docs/software/sciapps/quantumespresso.md

@@ -147,7 +147,12 @@ To recompile QE after editing the source code re-run `spack -e $SCRATCH/qe-env i
 uenv start quantumespresso/v7.3.1
 MPICH_GPU_SUPPORT_ENABLED=1 srun [...] $SCRATCH/qe-env/view/bin/pw.x < pw.in
 ```
-Note: The `pw.x` is linked to the uenv, it won't work without activating the uenv, also it will only work with the exact same version of the uenv. The physical installation path is in `$SCRATCH/spack`, deleting this directory will leave the anonymous spack environment created in 3. with dangling symlinks.
+
+!!! warning
+    The `pw.x` is linked to the uenv, it won't work without activating the uenv, also it will only work with the exact same version of the uenv. 
+
+!!! warning
+    The physical installation path is in `$SCRATCH/spack`, deleting this directory will leave the anonymous spack environment created in 3. with dangling symlinks.