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

docs/mkdocs.yml

@@ -47,18 +47,18 @@ exclude_docs: |
 nav:
   - Getting Started:
       - Overview: index.md
-      - Creating Your First Clan: guides/getting-started/index.md
+      - guides/getting-started/creating-your-first-clan.md
-      - Add Machines: guides/getting-started/add-machines.md
+      - guides/getting-started/add-machines.md
-      - Add User: guides/getting-started/add-user.md
+      - guides/getting-started/add-users.md
-      - Add Services: guides/getting-started/add-services.md
+      - guides/getting-started/add-services.md
       - Deploy to Physical Machine:
-          - Create USB Installer: guides/getting-started/create-installer.md
+          - guides/getting-started/deploy-to-physical-machine/flash-installer.md
-          - Deploy Physical Machine: guides/getting-started/hardware-report-physical.md
+          - guides/getting-started/deploy-to-physical-machine/install-machine.md
-      - Deploy to Virtual Machine: guides/getting-started/hardware-report-virtual.md
+      - guides/getting-started/deploy-to-virtual-machine.md
-      - Configure Disk Config: guides/getting-started/choose-disk.md
+      - guides/getting-started/configure-disk.md
-      - Update Machine: guides/getting-started/update.md
+      - guides/getting-started/update-machines.md
-      - Continuous Integration: guides/getting-started/flake-check.md
+      - guides/getting-started/continuous-integration.md
-      - Convert Existing NixOS Config: guides/getting-started/convert-flake.md
+      - guides/getting-started/convert-existing-NixOS-configuration.md
   - Guides:
       - Inventory:
           - Introduction to Inventory: guides/inventory/inventory.md

docs/nix/render_options/__init__.py

@@ -497,8 +497,8 @@ def produce_clan_options_docs() -> None:
     output = """# Clan Options
 This provides an overview of the available options
 
-Those can be set via [`clan-core.lib.clan`](./clan.md#inventory) function,
+Those can be set via [`clan-core.lib.clan`](/reference/options/clan.md#inventory) function,
-or via the [`clan`](./clan.md) attribute of flake-parts.
+or via the [`clan`](/reference/options/clan.md) attribute of flake-parts.
 
 """
     # Inventory options are already included under the clan attribute

docs/site/guides/disk-encryption.md

@@ -5,7 +5,7 @@ This guide provides an example setup for a single-disk ZFS system with native en
     This configuration only applies to `systemd-boot` enabled systems and **requires** UEFI booting.
 
 !!! Info "Secure Boot"
-    This guide is compatible with systems that have [secure boot disabled](./secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings.
+    This guide is compatible with systems that have [secure boot disabled](/guides/secure-boot.md). If you encounter boot issues, check if secure boot needs to be disabled in your UEFI settings.
 
 Replace the highlighted lines with your own disk-id.
 You can find our your disk-id by executing:

docs/site/guides/getting-started/add-machines.md

@@ -1,5 +1,3 @@
-# How to add machines
-
 Machines can be added using the following methods
 
 - Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md))

docs/site/guides/getting-started/add-services.md

@@ -1,5 +1,3 @@
-# How to add services
-
 A service in clan is a self-contained, reusable unit of system configuration that provides a specific piece of functionality across one or more machines.
 
 Think of it as a recipe for running a tool — like automatic backups, VPN networking, monitoring, etc.

docs/site/guides/getting-started/add-users.md

@@ -1,5 +1,3 @@
-# How to add users
-
 !!! Note "Under construction"
 
 The users concept of clan is not done yet. This guide outlines some solutions from our community.

docs/site/guides/getting-started/configure-disk.md

@@ -1,5 +1,3 @@
-# Configure Disk Config
-
 By default clan uses [disko](https://github.com/nix-community/disko) which allows for declarative disk partitioning.
 
 To see what disk templates are available run:

docs/site/guides/getting-started/convert-existing-NixOS-configuration.md

@@ -1,10 +1,8 @@
-# Convert existing NixOS configurations
-
 This guide will help you convert your existing NixOS configurations into a Clan.
 
 !!! Warning
     Migrating instead of starting new can be trickier and might lead to bugs or
-    unexpected issues. We recommend reading the [Getting Started](./index.md) guide first.
+    unexpected issues. We recommend reading the [Getting Started](/guides/getting-started/creating-your-first-clan.md) guide first.
 
     Once you have a working setup and understand the concepts transfering your NixOS configurations over is easy.
 

docs/site/guides/getting-started/creating-your-first-clan.md

@@ -1,5 +1,3 @@
-# :material-clock-fast: Getting Started
-
 Ready to manage your fleet of machines?
 
 We will create a declarative infrastructure using **clan**, **git**, and **nix flakes**.

docs/site/guides/getting-started/deploy-to-physical-machine/flash-installer.md

@@ -1,9 +1,7 @@
-# USB Installer Image for Physical Machines
-
 To install Clan on physical machines, you need to use our custom installer image. This is necessary for proper installation and operation.
 
 !!! note "Deploying to a Virtual Machine?"
-    If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](./hardware-report-virtual.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
+    If you're deploying to a virtual machine (VM), you can skip this section and go directly to the [Deploy Virtual Machine](/guides/getting-started/deploy-to-virtual-machine.md) step. In this scenario, we automatically use [nixos-anywhere](https://github.com/nix-community/nixos-anywhere) to replace the kernel during runtime.
 
 ??? info "Why nixos-anywhere Doesn't Work on Physical Hardware?"
     nixos-anywhere relies on [kexec](https://wiki.archlinux.org/title/Kexec) to replace the running kernel with our custom one. This method often has compatibility issues with real hardware, especially systems with dedicated graphics cards like laptops and servers, leading to crashes and black screens.
@@ -152,7 +150,7 @@ sudo umount /dev/sdb1
 
 ## Boot From USB Stick
 
-- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](../secure-boot.md)
+- To use, boot from the Clan USB drive with **secure boot turned off**. For step by step instructions go to [Disabling Secure Boot](/guides/)
 
 ## (Optional) Connect to Wifi Manually
 

docs/site/guides/getting-started/deploy-to-physical-machine/install-machine.md

@@ -1,18 +1,16 @@
-# Installing a Physical Machine
-
 Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
 
 
 ### Prerequisites
 - [x] RAM > 2GB
 - [x] **Two Computers**: You need one computer that you're getting ready (we'll call this the Target Computer) and another one to set it up from (we'll call this the Setup Computer). Make sure both can talk to each other over the network using SSH.
-- [x] **Machine configuration**: See our basic [adding and configuring machine guide](./add-machines.md)
+- [x] **Machine configuration**: See our basic [adding and configuring machine guide](/guides/getting-started/add-machines.md)
-- [x] **Initialized secrets**: See [secrets](../secrets.md) for how to initialize your secrets.
+- [x] **Initialized secrets**: See [secrets](/guides/secrets.md) for how to initialize your secrets.
-- [x] **USB Flash Drive**: See [Clan Installer](./create-installer.md)
+- [x] **USB Flash Drive**: See [Clan Installer](/guides/getting-started/flash-installer.md)
 
 
 ### Image Installer
-This method makes use of the [image installers](./create-installer.md).
+This method makes use of the [image installers](/guides/getting-started/flash-installer.md).
 
 The installer will randomly generate a password and local addresses on boot, then run a SSH server with these preconfigured.
 The installer shows its deployment relevant information in two formats, a text form, as well as a QR code.
@@ -68,7 +66,7 @@ This is an example of the booted installer.
     ```
 2.  The root password for the installer medium.
     This password is autogenerated and meant to be easily typeable.
-3.  See how to connect the installer medium to wlan [here](./create-installer.md).
+3.  See how to connect the installer medium to wlan [here](/guides/getting-started/flash-installer.md).
 
 !!!tip
     For easy sharing of deployment information via QR code, we highly recommend using [KDE Connect](https://apps.kde.org/de/kdeconnect/).
@@ -113,4 +111,4 @@ The following command will generate a hardware report with [nixos-facter](https:
 
 If you are using our template `[MACHINE]` would be `jon`
 
-[Next Step (Choose Disk Format)](./choose-disk.md){ .md-button .md-button--primary }
+[Next Step (Choose Disk Format)](/guides/getting-started/configure-disk.md){ .md-button .md-button--primary }

docs/site/guides/getting-started/deploy-to-virtual-machine.md

@@ -1,7 +1,3 @@
-# Generate a VM Hardware Report
-
-Now that you have created a machine, added some services, and set up secrets, this guide will walk you through how to deploy it.
-
 
 ## Prerequisites
 - [x] RAM > 2GB

docs/site/guides/getting-started/update-machines.md

@@ -1,4 +1,3 @@
-
 # Update Machines
 
 The Clan command line interface enables you to update machines remotely over SSH.

docs/site/guides/nixos-rebuild.md

@@ -64,5 +64,5 @@ nixos-rebuild switch --flake .#my-machine --target-host root@target-ip --build-h
 
 ## Related Documentation
 
-- [Update Your Machines](getting-started/update.md) - Using clan's update command
+- [Update Your Machines](/guides/getting-started/update-machine.md) - Using clan's update command
-- [Variables (Vars)](vars/vars-overview.md) - Understanding the vars system
+- [Variables (Vars)](/guides/vars/vars-overview.md) - Understanding the vars system

docs/site/index.md

@@ -85,7 +85,7 @@ hide:
 
 ---
 
-[Get started](./guides/getting-started/index.md){ .md-button .md-button--primary }
+[Get started](/guides/getting-started/creating-your-first-clan){ .md-button .md-button--primary }
 [View on Gitea](https://git.clan.lol/clan/clan-core){ .md-button }
 
 ## Guides

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/
+Further references:
-For more detailed information, visit: https://docs.clan.lol/guides/getting-started/hardware-report-physical
+
+- 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,

templates/clan/flake-parts/flake.nix

@@ -20,7 +20,7 @@
         inputs.clan-core.flakeModules.default
       ];
 
-      # https://docs.clan.lol/guides/getting-started/flake-parts/
+      # https://docs.clan.lol/guides/flake-parts
       clan = {
         imports = [ ./clan.nix ];
       };