docs: unify markdown files with documentation titles

This is preparational work to reduce the surface are of the different mappings

We want to reduce the following:

/guides/secrets.md -> Guides/getting started/How to use flakes with sops -> with '# Secrets Management'

- Title
- URI
- Filepath

should follow a stricter pattern to make it easy to maintain

pkgs/clan-cli/clan_cli/cli.py

@@ -179,7 +179,7 @@ Examples:
   Will create a new clan flake in the specified directory and create it if it
   doesn't exist yet. The flake will be created from a default template.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/index.html")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/creating-your-first-clan")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -253,7 +253,7 @@ Examples:
   $ clan flash write mymachine --disk main /dev/sd<X> --ssh-pubkey ~/.ssh/id_rsa.pub
   Will flash the machine 'mymachine' to the disk '/dev/sd<X>' with the ssh public key '~/.ssh/id_rsa.pub'.
 
-For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/create-installer")}
+For more detailed information, visit: {help_hyperlink("getting-started", "https://docs.clan.lol/guides/getting-started/deploy-to-physical-machine/flash-installer")}
             """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -280,7 +280,7 @@ Examples:
   the json string. [JSON] can either be a json formatted string itself, or point
   towards a file containing the deployment information
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/hardware-report-physical")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/deploy-to-physical-machine/install-machine")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -411,7 +411,7 @@ Examples:
   If the `--target-host` flag is omitted will try to find host information by
   checking the deployment configuration inside the specified machine.
 
-For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/update")}
+For more detailed information, visit: {help_hyperlink("deploy", "https://docs.clan.lol/guides/getting-started/update-machines")}
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,

pkgs/clan-cli/clan_cli/hyperlink.py

@@ -32,7 +32,7 @@ def help_hyperlink(description: str, url: str) -> str:
 
 def docs_hyperlink(description: str, url: str) -> str:
     """Returns a markdown hyperlink"""
-    url = url.replace("https://docs.clan.lol", "../..")
+    url = url.replace("https://docs.clan.lol", "/")
     url = url.replace("index.html", "index")
     url += ".md"
     return f"[{description}]({url})"

pkgs/clan-cli/clan_cli/machines/cli.py

@@ -48,7 +48,7 @@ Examples:
   $ clan machines update machine1 machine2 --tags production
   Will update only machine1 and machine2 if they both have the "production" tag.
 
-For more detailed information, visit: https://docs.clan.lol/guides/getting-started/update
+For more detailed information, visit: https://docs.clan.lol/guides/getting-started/update-machines
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,
@@ -108,9 +108,6 @@ Examples:
 
   $ clan machines init-hardware-config [MACHINE] --target-host root@<ip>
   Will generate the facter.json hardware report for `[TARGET_HOST]` and place the result in facter.json for the given machine `[MACHINE]`.
-
-For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration
-
 """
         ),
     )
@@ -129,9 +126,6 @@ For more detailed information, visit: https://docs.clan.lol/guides/getting-start
 
         $ clan machines update-hardware-config [MACHINE] --target-host root@<ip>
         Will generate the facter.json hardware report for `[TARGET_HOST]` and place the result in facter.json for the given machine `[MACHINE]`.
-
-        For more detailed information, visit: https://docs.clan.lol/guides/getting-started/configure/#machine-configuration
-
         """
         ),
     )
@@ -160,8 +154,10 @@ Examples:
   Will install the specified machine [MACHINE] to the host exposed by
   the deployment information of the [JSON] deployment string.
 
-For information on how to set up the installer see: https://docs.clan.lol/guides/getting-started/create-installer/
-For more detailed information, visit: https://docs.clan.lol/guides/getting-started/hardware-report-physical
+Further references:
+
+- https://docs.clan.lol/guides/getting-started/deploy-to-physical-machine/
+- https://docs.clan.lol/guides/getting-started/deploy-to-virtual-machine/
         """
         ),
         formatter_class=argparse.RawTextHelpFormatter,