clean up linking in docs

Author: bcumming

README.md

@@ -19,3 +19,12 @@ Before pushing, apply the linting rules (this calls uv under the hood):
 ```
 ./lint
 ```
+## building the docs
+
+The documentation for Stackinator is built from the markdown files in the `docs` path using MkDocs and MkDocs-material.
+You can view the latest documentation online at [github.io](https://eth-cscs.github.io/stackinator/)
+
+To view work in progress docs, run the serve script and follow the link it provides to view a local copy of the docs in your browser.
+```bash
+./serve
+```

docs/building.md

@@ -1,6 +1,7 @@
+[](){#ref-building}
 # Building Spack Stacks
 
-Once a stack has been [configured](configuring.md) using `stack-config`, it's time to build the software stack.
+Once a stack has been [configured][ref-configuring] using `stack-config`, it's time to build the software stack.
 
 ## How to Build
 
@@ -18,7 +19,7 @@ env --ignore-environment PATH=/usr/bin:/bin:`pwd -P`/spack/bin make modules stor
 The call to `make` is wrapped with with `env --ignore-env` to unset all environment variables, to improve reproducability of builds.
 
 Build times for stacks typically vary between 30 minutes to 3 hours, depending on the specific packages that have to be built.
-Using [build caches](build-caches.md) and building in shared memory (see below) are the most effective methods to speed up builds.
+Using [build caches][ref-mirrors] and building in shared memory (see below) are the most effective methods to speed up builds.
 
 ## Where to Build
 

docs/cluster-config.md

@@ -1,3 +1,4 @@
+[](){#ref-cluster-config}
 # Cluster Configuration
 
 Spack stacks are built on bare-metal clusters using a minimum of dependencies from the underlying system.
@@ -10,7 +11,7 @@ A cluster configuration is a directory with the following structure:
 └─ repos.yaml       # optional reference to additional site packages
 ```
 
-The configuration is provided during the [configuration](configuring.md) step with the `--system/-s` flag.
+The configuration is provided during the [configuration][ref-configuring] step with the `--system/-s` flag.
 The following example targets the Clariden system at CSCS:
 
 ```bash
@@ -98,7 +99,7 @@ packages:
 Mirrors and caches are **not** part of the system configuration.
 They are supplied per-invocation with `stack-config --mirror <file>`, because the locations involved (build caches, source caches) are often specific to the user running the build and may not be accessible to everyone using a system.
 
-See [Mirrors and Build Caches](build-caches.md) for the full reference and examples.
+See [Mirrors and Build Caches][ref-mirrors] for the full reference and examples.
 
 ## Site and System Configurations
 

docs/configuring.md

@@ -1,3 +1,4 @@
+[](){#ref-configuring}
 # Configuring Spack Stacks
 
 Stackinator generates the make files and spack configurations that build the spack environments that are packaged together in the spack stack.
@@ -10,13 +11,13 @@ stack-config --build $BUILD_PATH --recipe $RECIPE_PATH --system $SYSTEM_CONFIG_P
 
 The following flags are required:
 
-* `-b/--build`: the path where the [build](building.md) is to be performed.
-* `-r/--recipe`: the path with the [recipe](recipes.md) yaml files that describe the environment.
-* `-s/--system`: the path containing the [system configuration](cluster-config.md) for the target cluster.
+* `-b/--build`: the path where the [build][ref-building] is to be performed.
+* `-r/--recipe`: the path with the [recipe][ref-recipes] yaml files that describe the environment.
+* `-s/--system`: the path containing the [system configuration][ref-cluster-config] for the target cluster.
 
 The following flags are optional:
 
-* `--mirror`: path to a [mirrors.yaml](build-caches.md) file configuring build caches and mirrors.
+* `--mirror`: path to a [mirrors.yaml][ref-mirrors] file configuring build caches and mirrors.
 * `-c/--cache`: legacy build cache configuration file (deprecated; use `--mirror`).
 * `-m/--mount`: override the [mount point](installing.md) where the stack will be installed.
 * `--version`: print the stackinator version.

docs/installing.md

@@ -1,3 +1,4 @@
+[](){#ref-installing}
 # Installing Stacks
 
 The installation path of the software stack is set when the stack is configured.
@@ -45,4 +46,6 @@ The `store` sub-directory contains the full software stack installation tree.
 ### SquashFS installation
 
 The `store.squashfs` file is a compressed [SquashFS](https://tldp.org/HOWTO/SquashFS-HOWTO/whatis.html) image of the contents of the `store` path.
-This can be mounted at runtime using [`squashfs-mount`](https://github.com/eth-cscs/squashfs-mount) or the [Slurm plugin](https://github.com/eth-cscs/slurm-uenv-mount/), or mounted by a system-administrator using [`mount`](https://man7.org/linux/man-pages/man2/mount.2.html), in order the to take advantage of the benefits of SquashFS over shared file systems.
+This can be mounted at runtime using [`uenv`](https://github.com/eth-cscs/uenv) or the uenv Slurm plugin.
+
+Images can also be mounted by a system-administrator using [`mount`](https://man7.org/linux/man-pages/man2/mount.2.html), which is used in production at CSCS to permanantly mount software stacks used by the weather service on their operational cluster when nodes boot.

docs/mirrors.md

@@ -1,3 +1,4 @@
+[](){#ref-mirrors}
 # Mirrors and Build Caches
 
 Spack can use *mirrors* and *caches* to speed up image builds and to build on systems with limited or no internet access.
@@ -8,7 +9,7 @@ They are configured in a single YAML file passed to `stack-config` using the `--
 stack-config -b $build -r $recipe -s $system --mirror mirrors.yaml
 ```
 
-The file is not part of the [system configuration](cluster-config.md): mirror locations are usually specific to the person running the build, so each invocation provides its own.
+The file is not part of the [system configuration][ref-cluster-config]: mirror locations are usually specific to the person running the build, so each invocation provides its own.
 
 A `mirrors.yaml` can describe five kinds of entry, each optional and each documented below:
 

docs/readme.md

@@ -1,3 +1,4 @@
+[](){#ref-recipes}
 # Recipes
 
 A recipe is a description of all of the compilers and software packages to be installed, along with configuration of modules and environment scripts the stack will provide to users.