📝 Replace notes with admonitions

docs/using/troubleshooting.md

@@ -1,7 +1,7 @@
 # Troubleshooting Common Problems
 
 When troubleshooting, you may see unexpected behaviors or receive an error message. This section provides advice on
-how to identify and mitigate the cause of the problem and how to resolve it (for the most commlonly encountered issues).
+how to identify and mitigate the cause of the problem and how to resolve it (for the most commonly encountered issues).
 
 Most of the `docker run` flags used in this document are explained in detail in the [Common Features, Docker Options section](../using/common.html#Docker-Options) of the documentation.
 
@@ -29,6 +29,7 @@ touch: cannot touch 'stagingarea/kale.txt': Permission denied
 ```
 
 In this case the user of the container (`jovyan`) and the owner of the mounted volume (`root`) have different permission levels and ownership over the container's directories and mounts.
+The following sections cover a few of these scenarios and suggestions to fix these problems.
 
 **Some things to try:**
 
@@ -68,12 +69,12 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v
    -rw-r--r-- 1 jovyan users    0 Feb  1 14:41 kale.txt
    ```
 
-   **Additional notes:**
+   ```{admonition} Additional notes
-
+      - If you are mounting your volume inside the `/home/` directory, you can use the `-e CHOWN_HOME=yes` and `CHOWN_HOME_OPTS="-R"` flags instead of the `-e CHOWN_EXTRA`
-   - If you are mounting your volume inside the `/home/` directory, you can use the `-e CHOWN_HOME=yes` and `CHOWN_HOME_OPTS="-R"` flags instead of the `-e CHOWN_EXTRA`
+        and `-e CHOWN_EXTRA_OPTS` in the example above.
-     and `-e CHOWN_EXTRA_OPTS` in the example above.
+      - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name <my-volume>`
-   - This solution should work in most cases where you have created a docker volume (i.e. using the [`docker volume create --name <my-volume>`
+        command](https://docs.docker.com/storage/volumes/#create-and-manage-volumes)) and mounted it using the`-v` flag in `docker run`.
-     command](https://docs.docker.com/storage/volumes/#create-and-manage-volumes)) and mounted it using the`-v` flag in `docker run`.
+   ```
 
 2. **Matching the container's UID/GID with the host's**
 
@@ -81,7 +82,7 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v
 
    When you initialize a Docker container using the flag `-v`, the host directories are bind-mounted directly into the container.
    Therefore, the permissions and ownership are copied over and will be **the same** as the ones in your local host
-   (including user ids) which may result in permissions errors like the one displayed above.
+   (including user ids) which may result in permissions errors when trying to access directories or create/modify files inside.
 
    Suppose your local user has a `UID` and `GID` of `1234`. To fix the UID discrepancies between your local directories and the container's
    directories, you can run the container with an explicit `NB_UID` and `NB_GID` to match the that of the local user:
@@ -105,21 +106,15 @@ In this case the user of the container (`jovyan`) and the owner of the mounted v
    - `NB_IUD` and `NB_GID` should match the local user's UID and GID.
    - You must use `--user root` to ensure that the `UID` and `GID` are updated at runtime.
 
-   **Additional notes:**
+   ````{admonition} Additional notes
-
    - The caveat with this approach is that since these changes are applied at runtime, you will need to re-run the same command
      with the appropriate flags and environment variables if you need to recreate the container (i.e. after removing/destroying it).
-
+   - If you pass a numeric UID, it must be in the range of 0-2147483647
-   - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user, so from the above example you'd get the following:
+   - This approach only updates the UID and GID of the **existing `jovyan` user** instead of creating a new user. From the above example:
-
      ```bash
      $ id
      uid=1234(jovyan) gid=1234(jovyan) groups=1234(jovyan),100(users)
-     ```
+   ````
-
-   - If you pass a numeric UID, it must be in the range of 0-2147483647
-
-     If you need to specify a different user check the following section in this page.
 
 ## Permission issues after changing the UID/GIU and USER in the container
 
@@ -133,7 +128,7 @@ If on top of changing the UID and GID you also **need to create a new user**, yo
 
 1. **Ensure the new user has ownership of `/home` and volume mounts**
 
-   For example, say you want to create a user `callisto` with a `GID` and `UID` of 1234, you will have to add the following flags to the docker run command:
+   For example, say you want to create a user `callisto` with a `GID` and `UID` of `1234`, you will have to add the following flags to the docker run command:
 
    ```bash
     docker run -it --rm \
@@ -165,8 +160,13 @@ If on top of changing the UID and GID you also **need to create a new user**, yo
    - `-e CHOWN_HOME_OPTS="-R"` and `-e CHOWN_HOME=yes`: ensure that the new user is the owner of the `/home` directory and subdirectories
      (setting `CHOWN_HOME_OPTS="-R` will ensure this change is applied recursively)
    - `-w "/home/${NB_USER}"` sets the working directory to be the new user's home
-   - **mounting volumes**: in this case, the `-v` flag is used to mount the local volume onto the `/home` directory; if you, however, are mounting these volumes elsewhere,
+
-     you also need to use the `-e CHOWN_EXTRA=<some-dir>` flag to avoid any permission issues (see section above)
+   ```{admonition} Additional notes
+    In the example above, the `-v` flag is used to mount the local volume onto the `/home` directory of the new user.
+
+    However, if you are mounting a volume elsewhere, you also need to use the `-e CHOWN_EXTRA=<some-dir>` flag to avoid any permission
+    issues (see the section [Permission denied when mounting volumes](../using/troubleshooting.html#permission-denied-when-mounting-volumes) in this page).
+   ```
 
 2. **Dynamically assign the user ID and GID**
 
@@ -188,17 +188,17 @@ If on top of changing the UID and GID you also **need to create a new user**, yo
 
    where:
 
-   - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the new user (`callisto`) to that of the local user executing the run command
+   - `"$(id -u)" and "$(id -g)"` will dynamically assign the `UID` and `GID` of the user executing the `docker run` command to the new user (`callisto`)
 
 ## Additional tips and troubleshooting commands
 
-- Use absolute paths when using the `-v` flag:
+- Pass absolute paths to the `-v` flag:
 
   ```bash
   -v $(PWD)/<my-vol>:/home/jovyan/work
   ```
 
-  In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory. The destination
+  In this example, we use the syntax `$(PWD)`, which is replaced with the full path to the current directory at runtime. The destination
   path should also be an absolute path starting with a `/` such as `home/jovyan/work`.
 
 - You might want to consider using the Docker native `--user <UID>` and `--group-add users` flags instead of `-e NB_GID` and `-e NB_UID`: