update other markdowns

supernord · supernord · commit 7ce85a208b98 · 2026-07-08T15:51:20.000+09:30
diff --git a/pages/nextflow.md b/pages/nextflow.md
@@ -11,10 +11,8 @@ Nextflow runs each workflow process in its own environment. When using container
 pulls the required image automatically. On BioShell, you can override this behaviour by
 creating a config file that points processes to the existing CVMFS images.
 
-> **Note:** Nextflow always prioritises a `-config` file passed on the command line over the
-> workflow's built-in `nextflow.config`.
+{% include callout.html type="note" content="Nextflow always prioritises a `-config` file passed on the command line over the workflow's built-in `nextflow.config`." %}
 
----
 
 ## Using containers directly from CVMFS {#cvmfs-containers}
 
@@ -29,7 +27,6 @@ process {
 }
 ```
 
----
 
 ## Using an installed SHPC module {#shpc-module}
 
@@ -44,9 +41,8 @@ process {
 }
 ```
 
-> **Note:** The `module` value must match exactly what appears in `module avail`.
+{% include callout.html type="note" content="The `module` value must match exactly what appears in `module avail`." %}
 
----
 
 ## Running with your config override {#run}
 
diff --git a/pages/ssh-keys.md b/pages/ssh-keys.md
@@ -6,14 +6,14 @@ description: How to generate an SSH key pair on macOS, Linux, and Windows to aut
 BioShell uses SSH key authentication. This guide walks you through generating a key pair,
 copying your public key, and submitting it to the BioShell Onboarding Portal.
 
----
 
 ## Quick start {#quick-start}
 
 If you are familiar with SSH keys and just need the commands, use the steps below. For a
 full walkthrough including optional settings and troubleshooting, see the
 [step-by-step guide](#prerequisites) below.
 
+
 ### macOS and Linux
 
 ```bash
@@ -28,6 +28,7 @@ cat ~/.ssh/id_ed25519.pub
 
 Paste the output into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL).
 
+
 ### Windows
 
 ```powershell
@@ -42,7 +43,6 @@ cat $env:USERPROFILE\.ssh\id_ed25519.pub
 
 Paste the output into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add URL).
 
----
 
 ## Prerequisites {#prerequisites}
 
@@ -52,13 +52,13 @@ Paste the output into the [BioShell Onboarding Portal](AUTHOR TO SUPPLY — add
 | Linux | `openssh-client` — install with `sudo apt install openssh-client` or `sudo dnf install openssh` |
 | Windows | OpenSSH Client — built-in on Windows 10 (1809+) and Windows 11; enable via **Settings > Optional Features** if missing |
 
----
 
 ## Step 1: Generate the key pair {#generate}
 
 The recommended algorithm is **Ed25519** — it is fast, secure, and compact. Use RSA 4096
 only if a service requires it.
 
+
 ### macOS and Linux
 
 ```bash
@@ -110,7 +110,6 @@ Enter passphrase (empty for no passphrase):
 A passphrase encrypts your private key at rest. It is recommended for any key that will
 access production systems. Press **Enter** to skip.
 
----
 
 ## Step 2: Verify the key files {#verify}
 
@@ -121,6 +120,7 @@ After generation, two files are created:
 | `id_ed25519` | Private key — never share this |
 | `id_ed25519.pub` | Public key — share this with servers and services |
 
+
 ### macOS and Linux
 
 ```bash
@@ -133,7 +133,6 @@ ls -la ~/.ssh/
 dir $env:USERPROFILE\.ssh\
 ```
 
----
 
 ## Step 3: Add the key to ssh-agent (optional) {#ssh-agent}
 
@@ -146,14 +145,12 @@ Run the relevant command once after login:
 | Linux | `ssh-add ~/.ssh/id_ed25519` |
 | Windows (PowerShell) | `ssh-add $env:USERPROFILE\.ssh\id_ed25519` |
 
-> **Note:** On macOS the key is stored in Keychain and persists across reboots. On Linux
-> you may need to re-add the key after each session unless you configure your shell to start
-> the agent automatically.
+{% include callout.html type="note" content="On macOS the key is stored in Keychain and persists across reboots. On Linux you may need to re-add the key after each session unless you configure your shell to start the agent automatically." %}
 
----
 
 ## Step 4: Copy your public key {#copy-key}
 
+
 ### macOS
 
 ```bash
@@ -166,6 +163,7 @@ Or print it to copy manually:
 cat ~/.ssh/id_ed25519.pub
 ```
 
+
 ### Linux
 
 ```bash
@@ -176,6 +174,7 @@ xclip -selection clipboard < ~/.ssh/id_ed25519.pub
 cat ~/.ssh/id_ed25519.pub
 ```
 
+
 ### Windows
 
 ```powershell
@@ -186,7 +185,6 @@ Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard
 cat $env:USERPROFILE\.ssh\id_ed25519.pub
 ```
 
----
 
 ## Step 5: Submit your public key to BioShell {#submit}
 
@@ -198,10 +196,8 @@ cat $env:USERPROFILE\.ssh\id_ed25519.pub
 Your BioShell username will follow the convention `firstname.lastname`. Once your account is
 ready, return to the [Connecting to BioShell](access#connect) section of the access guide.
 
-> **Important:** If you run into any issues, contact
-> [AUTHOR TO SUPPLY — helpdesk email or link].
+{% include callout.html type="important" content="If you run into any issues, contact [AUTHOR TO SUPPLY — helpdesk email or link]." %}
 
----
 
 ## Managing multiple keys {#multiple-keys}
 
@@ -221,9 +217,8 @@ Host github.com
 
 With this config, connect to BioShell with `ssh bioshell`.
 
-> **Note:** On Windows this file lives at `C:\Users\you\.ssh\config`.
+{% include callout.html type="note" content="On Windows this file lives at `C:\Users\you\.ssh\config`." %}
 
----
 
 ## Key permissions (macOS and Linux) {#permissions}
 
@@ -237,7 +232,6 @@ chmod 600 ~/.ssh/config           # if it exists
 chmod 600 ~/.ssh/authorized_keys  # on servers
 ```
 
----
 
 ## Adding a key later {#add-key}
 
@@ -262,7 +256,6 @@ Then verify correct permissions on the server:
 ssh firstname.lastname@BIOSHELL_HOSTNAME "chmod 600 ~/.ssh/authorized_keys"
 ```
 
----
 
 ## Testing your connection {#testing}
 
@@ -276,7 +269,6 @@ Use `-v` for verbose output when troubleshooting:
 ssh -v firstname.lastname@BIOSHELL_HOSTNAME
 ```
 
----
 
 ## Algorithm reference {#algorithms}
 
diff --git a/pages/tools.md b/pages/tools.md
@@ -8,7 +8,6 @@ BioShell gives you access to thousands of bioinformatics tools and reference dat
 two underlying systems, **CVMFS** and **sHPC**, and a built-in assistant called **Shelley-Bio**
 that automates working with both.
 
----
 
 ## How the tooling stack works {#tooling-stack}
 
diff --git a/pages/training-development.md b/pages/training-development.md
@@ -3,18 +3,18 @@ title: Training development instructions
 description: How to set up and prepare a BioShell training environment for the BioCommons Training Cooperative, including VM configuration, CVMFS use, trainee directory layout, and pre-snapshot requirements.
 ---
 
-> **Draft:** These instructions are a work in progress. If anything is unclear, reach out to Mitchell directly. Feedback is very welcome.
+{% include callout.html type="warning" content="**Draft:** These instructions are a work in progress. If anything is unclear, reach out to Mitchell directly. Feedback is very welcome." %}
 
 This guide is for **training developers** (`tdevNN` users) who are setting up BioShell training environments for the BioCommons Training Cooperative. You will configure tools, build training materials, and prepare a template that gets automatically applied to trainee accounts when VMs are provisioned. When a VM is built from your snapshot by Giorgia or Mitchell, the provisioning script runs automatically: the trainee's username will be `userNN` (for example `user1`), their password is generated deterministically from their username and is unique per VM, the contents of `/etc/skel/` at snapshot time become the trainee's home directory, and `/etc/skel/` is cleared afterwards to reduce VM image size.
 
----
 
 ## VM setup and access {#vm-setup}
 
 ### Launch a VM instance
 
 VM instances are provisioned by Giorgia or Mitchell. Each dev machine is named with the prefix `D` followed by a number (for example `D1`).
 
+
 ### Log in via SSH
 
 The training team will provide you with a username and IP address. Your username follows the format `tdevNN`, where `NN` matches your VM's prefix number.
@@ -34,16 +34,16 @@ Once you have an active SSH connection, open your browser and go to:
 
 Replace `<IP_Address>` with the IP address provided by the training team.
 
----
 
 ## Developing training materials {#developing-materials}
 
 Set up your home directory (`/home/tdevNN`) exactly as you want trainees to experience it. Build and test your workflows there, using CVMFS containers and references throughout. The goal is a working, self-contained environment that a trainee could follow from start to finish.
 
-> **Keep data small:** When the Australian BioCommons dataset repository is ready, it will be the main access point for training data. Like CVMFS, data stored there will not count against VM size. Until then, use the minimum input data needed to demonstrate the workflow. If your ideal dataset is too large to copy to every trainee home directory, see [If resources are not available on CVMFS](#non-cvmfs) for how to pull it at boot time instead.
+{% include callout.html type="tip" content="**Keep data small:** When the Australian BioCommons dataset repository is ready, it will be the main access point for training data. Like CVMFS, data stored there will not count against VM size. Until then, use the minimum input data needed to demonstrate the workflow. If your ideal dataset is too large to copy to every trainee home directory, see [If resources are not available on CVMFS](#non-cvmfs) for how to pull it at boot time instead." %}
 
 Once everything works end-to-end, your home directory becomes the template.
 
+
 ### Disk budget {#disk-budget}
 
 The base VM template takes up approximately **12 GB** on a **30 GB** disk, leaving roughly **16 GB** of usable space. That space has to cover:
@@ -52,7 +52,7 @@ The base VM template takes up approximately **12 GB** on a **30 GB** disk, leavi
 - CVMFS-cached container layers and reference data (written to the CVMFS cache on first use)
 - Trainee working files generated during the session
 
-> **Watch the disk:** If the disk fills up during user creation, the `useradd` step will fail and the trainee account will not be created. Keep `/etc/skel/` as lean as possible.
+{% include callout.html type="tip" content="**Watch the disk:** If the disk fills up during user creation, the `useradd` step will fail and the trainee account will not be created. Keep `/etc/skel/` as lean as possible." %}
 
 Check how much space you have with:
 
@@ -115,7 +115,8 @@ This creates a symlink in your current directory pointing to the CVMFS source. Y
 ln -s /cvmfs/data.galaxyproject.org/byhand/CHM13_T2T_v2.0/seq/CHM13_T2T_v2.0.fa /path/to/destination/my_reference.fa
 ```
 
-> **Symlinks must use relative paths or CVMFS paths.** If you create a symlink pointing to an absolute path inside your home directory (for example `/home/tdev01/data/reference.fa`), that path will not exist on trainee VMs and the link will be broken. Always point symlinks either at a CVMFS path (absolute paths under `/cvmfs/` are safe because CVMFS is available on all VMs) or at a relative path within the directory structure that will be copied to `/etc/skel/`.
+{% include callout.html type="note" content="**Symlinks must use relative paths or CVMFS paths.** If you create a symlink pointing to an absolute path inside your home directory (for example `/home/tdev01/data/reference.fa`), that path will not exist on trainee VMs and the link will be broken. Always point symlinks either at a CVMFS path (absolute paths under `/cvmfs/` are safe because CVMFS is available on all VMs) or at a relative path within the directory structure that will be copied to `/etc/skel/`." %}
+
 
 ### RStudio and JupyterLab environments {#interactive-envs}
 
@@ -132,7 +133,9 @@ BiocManager::install("DESeq2")
 
 R writes packages to `~/R/x86_64-pc-linux-gnu-library/<version>/` by default. This directory will be picked up automatically when you copy your home directory to `/etc/skel/`.
 
-> **Watch the size:** R packages for workflows like scRNA-seq (Seurat, Bioconductor suites) can be several gigabytes. Check the size before copying:
+{% include callout.html type="tip" content="**Watch the size:** R packages for workflows like scRNA-seq (Seurat, Bioconductor suites) can be several gigabytes." %}
+
+Check the size before copying:
 
 ```bash
 du -sh ~/R/
@@ -156,6 +159,7 @@ du -sh ~/.local/
 
 If a required container or reference dataset is not on CVMFS and is too large to include directly in the trainee directory, it needs to be fetched at boot time via the VM provisioning script. Prepare the required scripts and share them with Giorgia or Mitchell.
 
+
 #### Adding a pull step to the provisioning script
 
 Downloads should be added before the `useradd` block, targeting the relevant folder inside `/etc/skel/`:
@@ -172,7 +176,8 @@ wget -q -O /home/$USERNAME/references/<file> <url>
 
 Resources pulled this way will appear in the correct location in the trainee's home directory, matching the layout described in [Trainee directory layout](#directory-layout).
 
-> **Note:** Boot-time pulls count toward your disk budget. Factor their size into your 30 GB total.
+{% include callout.html type="note" content="Boot-time pulls count toward your disk budget. Factor their size into your 30 GB total." %}
+
 
 ### Trainee directory layout {#directory-layout}
 
@@ -221,16 +226,17 @@ Once you are confident the template is correct, you can clean up your own home d
 rm -rf ~/*
 ```
 
-> **Tip:** Ask Giorgia or Mitchell to take a snapshot at key checkpoints if you want a backup before making significant changes.
+{% include callout.html type="tip" content="Ask Giorgia or Mitchell to take a snapshot at key checkpoints if you want a backup before making significant changes." %}
 
----
 
 ## Pre-snapshot requirements {#pre-snapshot}
 
+
 ### Cloud-init datasource check {#cloud-init}
 
 Running `apt upgrade` during VM setup can silently change cloud-init configuration, which causes all VMs built from your snapshot to inherit the wrong hostname. Please check and fix this before asking the VM to be snapshot.
 
+
 #### Step 1: Check for the offending apt file
 
 ```bash
@@ -257,13 +263,16 @@ datasource_list:
   - OpenStack
 ```
 
+
 #### Step 3: Clean cloud-init state
 
 ```bash
 sudo cloud-init clean --logs
 ```
 
-> **Important:** `cloud-init clean` deletes `/etc/cloud/ds-identify.cfg`. You will need to recreate it:
+{% include callout.html type="important" content="`cloud-init clean` deletes `/etc/cloud/ds-identify.cfg`." %}
+
+You will need to recreate it:
 
 ```bash
 sudo tee /etc/cloud/ds-identify.cfg << 'EOF'
@@ -279,6 +288,7 @@ cat /etc/cloud/ds-identify.cfg
 
 Expected output: `policy: enabled`
 
+
 #### Step 4: Confirm the datasource
 
 ```bash
diff --git a/pages/using-bioshell.md b/pages/using-bioshell.md
@@ -1,16 +1,25 @@
 ---
 title: Using BioShell
 description: Overview of BioShell's core features — tools, interactive environments, reference data, and workflow integration.
+tiles:
+  - title: "Accessing BioShell"
+    url: /access
+  - title: "Choose the right VM size (i.e. flavour) for my analysis"
+    url: /flavours
+  - title: "Connecting to BioShell"
+    url: /connecting
+  - title: "Find, install, and load a bioinformatics tool"
+    url: /tools
+  - title: "Work in a Jupyter or RStudio notebook"
+    url: /interactive
+  - title: "Run a Nextflow workflow using CVMFS containers"
+    url: /nextflow
 ---
 
 Once you are connected to your BioShell environment, you have access to a curated library
 of bioinformatics tools, interactive coding environments, and an AI-assisted support agent.
 
-Use the sections below to find what you need.
+#### Use the tiles below to find what you need
+
+{% include tiles-simple.html target = "tiles" col = "2" %}
 
-| I want to… | Go to |
-|-----------|-------|
-| Choose the right VM size for my analysis | [Choosing a flavour](flavours) |
-| Find, install, and load a bioinformatics tool | [Tools and reference data](tools) |
-| Work in a Jupyter or RStudio notebook | [Interactive environments](interactive) |
-| Run a Nextflow workflow using CVMFS containers | [Using Nextflow with CVMFS](nextflow) |
diff --git a/pages/why-bioshell.md b/pages/why-bioshell.md
