[docs] Fix cross-references in how-to guides (#4399)

The current implementation of internal linking to other pages/content
across the documentation set has been largely relative links.

Whilst this works and the link check CI passes, it does not scale well
over time. Usong the recommend Myst referencing standard is positive
because of the following reasons:

1. The links will still work even in situations where the linked
markdown page/file gets renamed or moved to a new folder
2. The user gets redirected to the exact heading in the destination page
3. Standardized naming of heading references.

MULTI-2157

Author: sharder996

docs/how-to-guides/index.md

@@ -23,7 +23,7 @@ Multipass allows you to create Ubuntu instances with a single command. As your n
 - [Add a network to an existing instance](manage-instances/add-a-network-to-an-existing-instance)
 - [Configure static IPs](manage-instances/configure-static-ips)
 - [Use a blueprint](manage-instances/use-a-blueprint)
-- [Use the Docker blueprint](manage-instances/use-the-docker-blueprint)
+- {ref}`how-to-guides-manage-instances-use-the-docker-blueprint`
 - [Run a Docker container in Multipass](manage-instances/run-a-docker-container-in-multipass)
 
 ## Customise Multipass

docs/how-to-guides/manage-instances/add-a-network-to-an-existing-instance.md

@@ -2,16 +2,16 @@
 # Add a network to an existing instance
 
 ```{seealso}
-[`networks`](/reference/command-line-interface/networks), [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`local.<instance-name>.bridged`](/reference/settings/local-instance-name-bridged)
-```
+[`networks`](reference-command-line-interface-networks), [`get`](reference-command-line-interface-get), [`set`](reference-command-line-interface-set), [`local.<instance-name>.bridged`](reference-settings-local-instance-name-bridged)
+````
 
 This guide explains how to bridge an existing Multipass instance with the available networks.
 
 ```{caution}
 This feature is available starting from Multipass version 1.14.
 ```
 
-First, you need to select a Multipass-wide preferred network to bridge with (you can always change it later). To do so, list all available networks using the [`multipass networks`](/reference/command-line-interface/networks) command. The output will be similar to the following:
+First, you need to select a Multipass-wide preferred network to bridge with (you can always change it later). To do so, list all available networks using the [`multipass networks`](reference-command-line-interface-networks) command. The output will be similar to the following:
 
 ```{code-block} text
 Name      Type       Description
@@ -24,19 +24,19 @@ mpbr0     bridge     Network bridge for Multipass
 virbr0    bridge     Network bridge
 ```
 
-Set the preferred network (for example, `eth0`) using the [`set`](/reference/command-line-interface/set) command:
+Set the preferred network (for example, `eth0`) using the [`set`](reference-command-line-interface-set) command:
 
 ```{code-block} text
 multipass set local.bridged-network=eth0
 ```
 
-Before bridging the network, you need to stop the instance (called `ultimate-grosbeak` in our example) using the [`stop`](/reference/command-line-interface/stop) command:
+Before bridging the network, you need to stop the instance (called `ultimate-grosbeak` in our example) using the [`stop`](reference-command-line-interface-stop) command:
 
 ```{code-block} text
 multipass stop ultimate-grosbeak
 ```
 
-You can now ask Multipass to bridge your preferred network using the [`local.<instance-name>.bridged`](/reference/settings/local-instance-name-bridged) setting:
+You can now ask Multipass to bridge your preferred network using the [`local.<instance-name>.bridged`](reference-settings-local-instance-name-bridged) setting:
 
 ```{code-block} text
 multipass set local.ultimate-grosbeak.bridged=true
@@ -49,15 +49,15 @@ multipass set local.bridged-network=eth1
 multipass set local.ultimate-grosbeak.bridged=true
 ```
 
-Use the [`get`](/reference/command-line-interface/get) command to check whether an instance is bridged with the currently configured preferred network:
+Use the [`get`](reference-command-line-interface-get) command to check whether an instance is bridged with the currently configured preferred network:
 
 ```{code-block} text
 multipass get local.ultimate-grosbeak.bridged
 ```
 
 After following the recipe above, the result should be `true`.
 
-Now, [`start`](/reference/command-line-interface/start) the instance.
+Now, [`start`](reference-command-line-interface-start) the instance.
 
 ```{code-block} text
 multipass start ultimate-grosbeak

docs/how-to-guides/manage-instances/configure-static-ips.md

@@ -1,7 +1,7 @@
 (how-to-guides-manage-instances-configure-static-ips)=
 # Configure static IPs
 
-> See also: [Instance](/explanation/instance)
+> See also: [Instance](explanation-instance)
 
 This guide explains how to create instances with static IPs in a new network, internal to the host. With this approach, instances get an extra IP that does not change with restarts. By using a separate, local network we avoid any IP conflicts. Instances retain the usual default interface with a DHCP-allocated IP, which gives them connectivity to the outside.
 

docs/how-to-guides/manage-instances/create-an-instance.md

@@ -1,13 +1,13 @@
 (how-to-guides-manage-instances-create-an-instance)=
 # Create an instance
 
-> See also: [`launch`](/reference/command-line-interface/launch), [Instance](/explanation/instance)
+> See also: [`launch`](reference-command-line-interface-launch), [Instance](explanation-instance)
 
 This document demonstrates various ways to create an instance with Multipass. While every method is a one-liner involving the command `multipass launch`, each showcases a different option that you can use to get exactly the instance that you want.
 
 ## Create an instance
 
-> See also: [`launch`](/reference/command-line-interface/launch), [`info`](/reference/command-line-interface/info)
+> See also: [`launch`](reference-command-line-interface-launch), [`info`](reference-command-line-interface-info)
 
 To create an instance with Multipass, run the command `multipass launch`. This launches a new instance, which is randomly named; for example:
 
@@ -32,7 +32,7 @@ Memory usage:   71.6M out of 985.4M
 
 ## Create an instance with a specific image
 
-> See also: [`find`](/reference/command-line-interface/find), [`launch <image>`](/reference/command-line-interface/launch), [`info`](/reference/command-line-interface/info)
+> See also: [`find`](reference-command-line-interface-find), [`launch <image>`](reference-command-line-interface-launch), [`info`](reference-command-line-interface-info)
 
 To find out which images are available, run `multipass find`. Here's a sample output:
 
@@ -77,7 +77,7 @@ Mounts:         --
 
 ## Create an instance with a custom name
 
-> See also: [`launch --name`](/reference/command-line-interface/launch)
+> See also: [`launch --name`](reference-command-line-interface-launch)
 
 To launch an instance with a specific name, add the `--name` option to the command line; for example `multipass launch kinetic --name helpful-duck`:
 
@@ -88,7 +88,7 @@ Launched: helpful-duck
 
 ## Create an instance with custom CPU number, disk and RAM
 
-> See also: [`launch --cpus --disk --memory`](/reference/command-line-interface/launch)
+> See also: [`launch --cpus --disk --memory`](reference-command-line-interface-launch)
 
 You can specify a custom number of CPUs, disk and RAM size using the `--cpus`, `--disk` and `--memory` arguments, respectively. For example:
 
@@ -98,22 +98,22 @@ multipass launch --cpus 4 --disk 20G --memory 8G
 
 ## Create an instance with primary status
 
-> See also: [`launch --name primary`](/reference/command-line-interface/launch)
+> See also: [`launch --name primary`](reference-command-line-interface-launch)
 
 An instance can obtain the primary status at creation time if its name is `primary`:
 
 ```{code-block} text
 multipass launch kinetic --name primary
 ```
 
-For more information, see [How to use the primary instance](/how-to-guides/manage-instances/use-the-primary-instance).
+For more information, see [How to use the primary instance](how-to-guides-manage-instances-use-the-primary-instance).
 
 (create-an-instance-with-multiple-network-interfaces)=
 ## Create an instance with multiple network interfaces
 
-> See also: [`launch --network`](/reference/command-line-interface/launch)
+> See also: [`launch --network`](reference-command-line-interface-launch)
 
-Multipass can create instances with additional network interfaces using the `multipass launch` command with the `--network` option. This is complemented by the [`networks`](/reference/command-line-interface/networks) command, that you can use to find available host networks to bridge with.
+Multipass can create instances with additional network interfaces using the `multipass launch` command with the `--network` option. This is complemented by the [`networks`](reference-command-line-interface-networks) command, that you can use to find available host networks to bridge with.
 
 This feature is only supported for images with [`cloud-init` support for v2 network config](https://cloudinit.readthedocs.io/en/latest/topics/network-config-format-v2.html), which in turn requires [netplan](https://netplan.io/) to be installed, meaning that you'll require Ubuntu 17.10 and Ubuntu Core 16 (except `snapcraft:core16`) or later. More specifically, this feature is only supported in the following scenarios:
 
@@ -123,7 +123,7 @@ This feature is only supported for images with [`cloud-init` support for v2 netw
 
 The `--network` option can be given multiple times to request multiple network interfaces beyond the default one, which is always present. Each time you add the `--network` option you also need to provide an argument specifying the properties of the desired interface:
 
-- `name` - This is the only required value, used to identify the host network to connect the instance's device to (see [`networks`](/reference/command-line-interface/networks) for possible values).
+- `name` - This is the only required value, used to identify the host network to connect the instance's device to (see [`networks`](reference-command-line-interface-networks) for possible values).
 - `mode` - Either `auto` (default) or `manual`; with `auto`, the instance will attempt to configure the network automatically.
 - `mac` - Custom MAC address to use for the device.
 
@@ -231,11 +231,11 @@ Another option is to install `NetworkManager`, but other network handlers need t
 
 ## Create an instance with a custom DNS
 
-In some scenarios the default of using the system-provided DNS will not be sufficient. When that's the case, you can use the `--cloud-init` option to the [`launch`](/reference/command-line-interface/launch) command, or modify the networking configuration after the instance started.
+In some scenarios the default of using the system-provided DNS will not be sufficient. When that's the case, you can use the `--cloud-init` option to the [`launch`](reference-command-line-interface-launch) command, or modify the networking configuration after the instance started.
 
 ### The `--cloud-init` approach
 
-> See also: [`launch --cloud-init`](/reference/command-line-interface/launch)
+> See also: [`launch --cloud-init`](reference-command-line-interface-launch)
 
 To use a custom DNS in your instances, you can use this `cloud-init` snippet:
 

docs/how-to-guides/manage-instances/index.md

@@ -15,8 +15,8 @@ Multipass allows you to create Ubuntu instances with a single command. As your n
 - [Remove an instance](how-to-guides-manage-instances-remove-an-instance)
 - [Add a network to an existing instance](how-to-guides-manage-instances-add-a-network-to-an-existing-instance)
 - [Configure static IPs](how-to-guides-manage-instances-configure-static-ips)
-- [Use a blueprint](how-to-guides-manage-instances-use-a-blueprint)
-- [Use the Docker blueprint](how-to-guides-manage-instances-use-the-docker-blueprint)
+- {ref}`how-to-guides-manage-instances-use-a-blueprint`
+- {ref}`how-to-guides-manage-instances-use-the-docker-blueprint`
 - [Run a Docker container in Multipass](how-to-guides-manage-instances-run-a-docker-container-in-multipass)
 
 ```{toctree}

docs/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init.md

@@ -6,6 +6,7 @@ You can set up instances with a customized environment or configuration using th
 Below are some common examples of using `cloud-init` with Multipass to create customized instances. The `cloud-init` file is provided by the Multipass team, but users are free to create and use their own personal `cloud-init` configurations.
 
 ## 📦 anbox-cloud-appliance
+
 Launch with:
 ```{code-block} text
 multipass launch \
@@ -16,8 +17,11 @@ multipass launch \
   --timeout 900 \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-anbox.yaml
 ```
+
 ## ⚙️ charm-dev
+
 Launch with:
+
 ```{code-block} text
 multipass launch 24.04 \
   --name charm-dev \
@@ -27,7 +31,9 @@ multipass launch 24.04 \
   --timeout 1800 \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-charm-dev.yaml
 ```
+
 Health check:
+
 ```{code-block} text
 multipass exec charm-dev -- bash -c "
  set -e
@@ -38,8 +44,11 @@ multipass exec charm-dev -- bash -c "
  charmcraft pack
 "
 ```
+
 ## 🐳 docker
+
 Launch with:
+
 ```{code-block} text
 multipass launch 24.04 \
   --name docker \
@@ -48,10 +57,13 @@ multipass launch 24.04 \
   --disk 40G \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-docker.yaml
 ```
+
 Health check:
+
 ```{code-block} text
 multipass exec docker -- bash -c "docker run hello-world"
 ```
+
 You can also optionally add aliases:
 
 ```{code-block} text
@@ -61,10 +73,13 @@ multipass alias docker:docker-compose docker-compose
 multipass prefer default
 multipass aliases
 ```
-> See also: [`How to use command aliases`](/how-to-guides/manage-instances/use-instance-command-aliases)
+
+> See also: [`How to use command aliases`](how-to-guides-manage-instances-use-instance-command-aliases)
 
 ## 🎞️ jellyfin
+
 Launch with:
+
 ```{code-block} text
 multipass launch 22.04 \
   --name jellyfin \
@@ -75,7 +90,9 @@ multipass launch 22.04 \
 ```
 
 ## ☸️ minikube
+
 Launch with:
+
 ```{code-block} text
 multipass launch \
   --name minikube \
@@ -85,15 +102,19 @@ multipass launch \
   --timeout 1800 \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-minikube.yaml
 ```
+
 Health check:
+
 ```{code-block} text
 multipass exec minikube -- bash -c "set -e
   minikube status
   kubectl cluster-info"
 ```
 
 ## 🤖 ros2-humble
+
 Launch with:
+
 ```{code-block} text
 multipass launch 22.04 \
   --name ros2-humble \
@@ -103,7 +124,9 @@ multipass launch 22.04 \
   --timeout 1800 \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-ros2-humble.yaml
 ```
+
 Heath check:
+
 ```{code-block} text
 multipass exec ros2-humble -- bash -c "
   set -e
@@ -116,8 +139,11 @@ multipass exec ros2-humble -- bash -c "
   ls /opt/ros/humble
 "
 ```
+
 ## 🤖 ros2-jazzy
+
 Launch with:
+
 ```{code-block} text
 multipass launch 24.04 \
   --name ros2-jazzy \
@@ -127,7 +153,9 @@ multipass launch 24.04 \
   --timeout 1800 \
   --cloud-init https://raw.githubusercontent.com/canonical/multipass/refs/heads/main/data/cloud-init-yaml/cloud-init-ros2-jazzy.yaml
 ```
+
 Health check:
+
 ```{code-block} text
 multipass exec ros2-jazzy -- bash -c "
   set -e

docs/how-to-guides/manage-instances/modify-an-instance.md

@@ -1,18 +1,18 @@
 (how-to-guides-manage-instances-modify-an-instance)=
 # Modify an instance
 
-> See also: [Instance](/explanation/instance), [`launch`](/reference/command-line-interface/launch), [`set`](/reference/command-line-interface/set), [Settings](/reference/settings/index)
+> See also: [Instance](explanation-instance), [`launch`](reference-command-line-interface-launch), [`set`](reference-command-line-interface-set), [Settings](reference-settings-index)
 
-This document shows further ways to customise an instance outside of the [`launch`](/reference/command-line-interface/launch) command using the Multipass [settings](/reference/settings/index).
+This document shows further ways to customise an instance outside of the [`launch`](reference-command-line-interface-launch) command using the Multipass [settings](reference-settings-index).
 
 (set-the-cpu-ram-or-disk-of-an-instance)=
 ## Set the CPUs , RAM or disk space of an instance
 
-> See also:  [`local.<instance-name>.cpus`](/reference/settings/local-instance-name-cpus), [`local.<instance-name>.disk)`](/reference/settings/local-instance-name-disk), [`local.<instance-name>.memory`](/reference/settings/local-instance-name-memory)
+> See also:  [`local.<instance-name>.cpus`](reference-settings-local-instance-name-cpus), [`local.<instance-name>.disk)`](reference-settings-local-instance-name-disk), [`local.<instance-name>.memory`](reference-settings-local-instance-name-memory)
 
 You can set instance properties at `launch` time, but you can also update some of them after the instance has been created. Specifically, an instance’s memory, disk space, and the number of its CPUs are exposed via daemon settings: `local.<instance-name>.(cpus|disk|memory)`.
 
-To modify one of this properties, first stop the instance and then issue the [`set`](/reference/command-line-interface/set) command. For example:
+To modify one of this properties, first stop the instance and then issue the [`set`](reference-command-line-interface-set) command. For example:
 
 ```{code-block} text
 multipass stop handsome-ling
@@ -63,7 +63,7 @@ Modifying instance settings is not supported when using the Hyperkit driver, whi
 
 ## Set the status of an instance to primary
 
-> See also:  [client.primary-name](/reference/settings/client-primary-name)
+> See also:  [client.primary-name](reference-settings-client-primary-name)
 
 This section demonstrates how to set the status of an instance to primary. This is convenient because it makes this instance the default argument for several commands, such as `shell` , `start` , `stop` , `restart` and `suspend`, and also automatically mounts your $HOME directory into the instance.
 

docs/how-to-guides/manage-instances/remove-an-instance.md

@@ -1,13 +1,13 @@
 (how-to-guides-manage-instances-remove-an-instance)=
 # Remove an instance
 
-> See also: [Instance](/explanation/instance)
+> See also: [Instance](explanation-instance)
 
 This guide demonstrates how to remove an instance, either temporarily or permanently.
 
 ## Move an instance to the recycle bin
 
-> See also: [`delete`](/reference/command-line-interface/launch), [`recover`](/reference/command-line-interface/recover)
+> See also: [`delete`](reference-command-line-interface-delete), [`recover`](reference-command-line-interface-recover)
 
 To mark an instance as deleted, run:
 
@@ -43,7 +43,7 @@ keen-yak                STOPPED           --               Ubuntu 18.04 LTS
 
 ## Remove an instance permanently
 
-> See also: [`delete`](/reference/command-line-interface/launch), [`purge`](/reference/command-line-interface/purge)
+> See also: [`delete`](reference-command-line-interface-delete), [`purge`](reference-command-line-interface-purge)
 
 If you want to get rid of all instances in `Deleted` status for good, you can purge them:
 

docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md

@@ -1,7 +1,8 @@
 (how-to-guides-manage-instances-run-a-docker-container-in-multipass)=
 # Run a Docker container in Multipass
+
 ```{Warning}
-Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. Find out more at: [Launch customized instances with Multipass and cloud-init](/how-to-guides/manage-instances/launch-customized-instances-with-multipass-and-cloud-init)
+Blueprints are deprecated and will be removed in a future release. You can achieve similar effects with cloud-init and other launch options. Find out more at: [Launch customized instances with Multipass and cloud-init](how-to-guides-manage-instances-launch-customized-instances-with-multipass-and-cloud-init)
 ```
 <!-- This is published as an Ubuntu Tutorial at this link: https://ubuntu.com/tutorials/running-a-container-with-the-docker-workflow-in-multipass -->
 
@@ -36,7 +37,7 @@ In this tutorial, you will see how to get started with the Docker blueprint by c
 
 *Duration: 3 minutes*
 
-Let's start by installing Multipass on your machine, following the steps in [How to install Multipass](/how-to-guides/install-multipass).
+Let's start by installing Multipass on your machine, following the steps in [How to install Multipass](how-to-guides-install-multipass).
 
 <!-- Out of date and unnecessary
 ![|720x643](https://assets.ubuntu.com/v1/25ca03d0-mp-docker.png)