From 08c2d574ce54ec6a11b056fa625543562b8001aa Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Fri, 3 Oct 2025 17:31:42 +0200
Subject: [PATCH] docs: use absolute page URI

This allows us to migrate to any framework that uses normal uri's
We just need to strip all .md endings in a simple grep command
---
 docs/nix/render_options/__init__.py           | 10 ++--
 .../deploy-to-virtual-machine.md              |  2 +-
 docs/site/guides/backups/backup-intro.md      |  2 +-
 docs/site/guides/contributing/debugging.md    |  2 +-
 docs/site/guides/inventory/clanServices.md    | 12 ++---
 docs/site/guides/macos.md                     |  2 +-
 docs/site/guides/migrations/disk-id.md        |  2 +-
 .../migrations/migrate-inventory-services.md  | 50 +++++++++----------
 .../guides/migrations/migration-facts-vars.md | 16 +++---
 docs/site/guides/secrets.md                   |  6 +--
 docs/site/guides/vars/vars-backend.md         |  2 +-
 docs/site/guides/vars/vars-overview.md        |  2 +-
 docs/site/index.md                            | 10 ++--
 lib/modules/clan/interface.nix                |  2 +-
 lib/modules/inventoryClass/inventory.nix      |  2 +-
 15 files changed, 61 insertions(+), 61 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index c37e2d730..7ede55c15 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -235,7 +235,7 @@ def produce_clan_core_docs() -> None:
             if module_type is not None and "submodule" not in module_type:
                 continue
             core_outputs[indexfile] += (
-                f"      - [{submodule_name}](./{submodule_name}.md)\n"
+                f"      - [{submodule_name}](/reference/clan.core/{submodule_name}.md)\n"
             )
 
         core_outputs[indexfile] += options_head
@@ -325,9 +325,9 @@ Each `clanService`:
 !!! Note
     `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`.
 
-    See [Migration Guide](../../guides/migrations/migrate-inventory-services.md) for help on migrating.
+    See [Migration Guide](/guides/migrations/migrate-inventory-services.md) for help on migrating.
 
-Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/inventory/clanServices.md).
+Learn how to use `clanServices` in practice in the [Using clanServices guide](/guides/inventory/clanServices.md).
 """
 
     with indexfile.open("w") as of:
@@ -422,7 +422,7 @@ Typically needed by module authors to define roles, behavior and metadata for di
 !!! Note
     This is not a user-facing documentation, but rather meant as a reference for *module authors*
 
-    See: [clanService Authoring Guide](../../guides/services/community.md)
+    See: [clanService Authoring Guide](/guides/services/community.md)
 """
     # Inventory options are already included under the clan attribute
     # We just omitted them in the clan docs, because we want a separate output for the inventory model
@@ -497,7 +497,7 @@ 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`](/reference/options/clan.md#inventory) function,
+Those can be set via [`clan-core.lib.clan`](/reference/options/clan.md) function,
 or via the [`clan`](/reference/options/clan.md) attribute of flake-parts.
 
 """
diff --git a/docs/site/getting-started/deploy-to-virtual-machine.md b/docs/site/getting-started/deploy-to-virtual-machine.md
index bbd2778da..b191c4d45 100644
--- a/docs/site/getting-started/deploy-to-virtual-machine.md
+++ b/docs/site/getting-started/deploy-to-virtual-machine.md
@@ -2,7 +2,7 @@
 ## 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](/getting-started/add-machines.md)
 
 
 Clan supports any cloud machine if it is reachable via SSH and supports `kexec`.
diff --git a/docs/site/guides/backups/backup-intro.md b/docs/site/guides/backups/backup-intro.md
index 1a46d3559..67039be93 100644
--- a/docs/site/guides/backups/backup-intro.md
+++ b/docs/site/guides/backups/backup-intro.md
@@ -4,7 +4,7 @@ This guide explains how to use the Clan backup and state management interface to
 
 ## State Management
 
-Clan backups are based on the concept of [states](../../reference/clan.core/state.md). A state is a Nix attribute set, defined as `clan.core.state.<name> = {};`, which specifies the files or directories to back up.
+Clan backups are based on the concept of [states](/reference/clan.core/state.md). A state is a Nix attribute set, defined as `clan.core.state.<name> = {};`, which specifies the files or directories to back up.
 
 For example, if you have a clan service called `linkding`, you can define the folders to back up as follows:
 
diff --git a/docs/site/guides/contributing/debugging.md b/docs/site/guides/contributing/debugging.md
index 36fcd2dfe..6ed2620ed 100644
--- a/docs/site/guides/contributing/debugging.md
+++ b/docs/site/guides/contributing/debugging.md
@@ -26,7 +26,7 @@ pkgs.mkShell {
 
 ## Debugging nixos-anywhere
 
-If you encounter a bug in a complex shell script such as `nixos-anywhere`, start by replacing the `nixos-anywhere` command with a local checkout of the project, look in the [contribution](./CONTRIBUTING.md) section for an example. 
+If you encounter a bug in a complex shell script such as `nixos-anywhere`, start by replacing the `nixos-anywhere` command with a local checkout of the project, look in the [contribution](/guides/CONTRIBUTING.md) section for an example.
 
 ## The Debug Flag
 
diff --git a/docs/site/guides/inventory/clanServices.md b/docs/site/guides/inventory/clanServices.md
index cd590a33f..a2ed7ea7e 100644
--- a/docs/site/guides/inventory/clanServices.md
+++ b/docs/site/guides/inventory/clanServices.md
@@ -68,7 +68,7 @@ inventory.instances = {
 ## Module Settings
 
 Each role might expose configurable options. See clan's [clanServices
-reference](../../reference/clanServices/index.md) for all available options.
+reference](/reference/clanServices/index.md) for all available options.
 
 Settings can be set in per-machine or per-role. The latter is applied to all
 machines that are assigned to that role.
@@ -155,13 +155,13 @@ inventory.instances = {
 
 You can use services exposed by Clan's core module library, `clan-core`.
 
-🔗 See: [List of Available Services in clan-core](../../reference/clanServices/index.md)
+🔗 See: [List of Available Services in clan-core](/reference/clanServices/index.md)
 
 ## Defining Your Own Service
 
 You can also author your own `clanService` modules.
 
-🔗 Learn how to write your own service: [Authoring a service](../services/community.md)
+🔗 Learn how to write your own service: [Authoring a service](/guides/services/community.md)
 
 You might expose your service module from your flake — this makes it easy for other people to also use your module in their clan.
 
@@ -177,7 +177,5 @@ ______________________________________________________________________
 
 ## What's Next?
 
-- [Author your own clanService →](../services/community.md)
-- [Migrate from clanModules →](../migrations/migrate-inventory-services.md)
-
-<!-- TODO: * [Understand the architecture →](../explanation/clan-architecture.md) -->
+- [Author your own clanService →](/guides/services/community.md)
+- [Migrate from clanModules →](/guides/migrations/migrate-inventory-services.md)
diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md
index 8b388fd10..31d4c7215 100644
--- a/docs/site/guides/macos.md
+++ b/docs/site/guides/macos.md
@@ -7,7 +7,7 @@ This guide explains how to manage macOS machines using Clan.
 Currently, Clan supports the following features for macOS:
 
 - `clan machines update` for existing [nix-darwin](https://github.com/nix-darwin/nix-darwin) installations
-- Support for [vars](./vars/vars-overview.md)
+- Support for [vars](/guides/vars/vars-overview.md)
 
 ## Add Your Machine to Your Clan Flake
 
diff --git a/docs/site/guides/migrations/disk-id.md b/docs/site/guides/migrations/disk-id.md
index f71d63d11..747ab52c0 100644
--- a/docs/site/guides/migrations/disk-id.md
+++ b/docs/site/guides/migrations/disk-id.md
@@ -95,4 +95,4 @@ We are going to make three changes:
 
 These steps are only needed for existing configurations that depend on the `diskId` module.
 
-For newer machines clan offers simple *disk templates* via its [templates cli](../../reference/cli/templates.md)
+For newer machines clan offers simple *disk templates* via its [templates cli](/reference/cli/templates.md)
diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md
index 085d91937..bf44a8a20 100644
--- a/docs/site/guides/migrations/migrate-inventory-services.md
+++ b/docs/site/guides/migrations/migrate-inventory-services.md
@@ -1,7 +1,7 @@
 # Migrating from using `clanModules` to `clanServices`
 
 **Audience**: This is a guide for **people using `clanModules`**.
-If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../services/community.md)
+If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](/guides/services/community.md)
 
 ## What's Changing?
 
@@ -157,7 +157,7 @@ instances = {
 
 ### Move `services` entries to `instances`
 
-Check if a service that you use has been migrated [In our reference](../../reference/clanServices/index.md)
+Check if a service that you use has been migrated [In our reference](/reference/clanServices/index.md)
 
 In your inventory, move it from:
 
@@ -247,45 +247,45 @@ The following table shows the migration status of each deprecated clanModule:
 
 | clanModule               | Migration Status                                                  | Notes                                                            |
 |--------------------------|-------------------------------------------------------------------|------------------------------------------------------------------|
-| `admin`                  | ✅ [Migrated](../../reference/clanServices/admin.md)              |                                                                  |
+| `admin`                  | ✅ [Migrated](/reference/clanServices/admin.md)              |                                                                  |
 | `auto-upgrade`           | ❌ Removed                                                        |                                                                  |
 | `borgbackup-static`      | ❌ Removed                                                        |                                                                  |
-| `borgbackup`             | ✅ [Migrated](../../reference/clanServices/borgbackup.md)         |                                                                  |
-| `data-mesher`            | ✅ [Migrated](../../reference/clanServices/data-mesher.md)        |                                                                  |
+| `borgbackup`             | ✅ [Migrated](/reference/clanServices/borgbackup.md)         |                                                                  |
+| `data-mesher`            | ✅ [Migrated](/reference/clanServices/data-mesher.md)        |                                                                  |
 | `deltachat`              | ❌ Removed                                                        |                                                                  |
 | `disk-id`                | ❌ Removed                                                        |                                                                  |
-| `dyndns`                 | ✅ [Migrated](../../reference/clanServices/dyndns.md)             |                                                                  |
+| `dyndns`                 | ✅ [Migrated](/reference/clanServices/dyndns.md)             |                                                                  |
 | `ergochat`               | ❌ Removed                                                        |                                                                  |
-| `garage`                 | ✅ [Migrated](../../reference/clanServices/garage.md)             |                                                                  |
+| `garage`                 | ✅ [Migrated](/reference/clanServices/garage.md)             |                                                                  |
 | `golem-provider`         | ❌ Removed                                                        |                                                                  |
 | `heisenbridge`           | ❌ Removed                                                        |                                                                  |
-| `importer`               | ✅ [Migrated](../../reference/clanServices/importer.md)           |                                                                  |
-| `iwd`                    | ❌ Removed                                                        | Use [wifi service](../../reference/clanServices/wifi.md) instead |
-| `localbackup`            | ✅ [Migrated](../../reference/clanServices/localbackup.md)        |                                                                  |
+| `importer`               | ✅ [Migrated](/reference/clanServices/importer.md)           |                                                                  |
+| `iwd`                    | ❌ Removed                                                        | Use [wifi service](/reference/clanServices/wifi.md) instead |
+| `localbackup`            | ✅ [Migrated](/reference/clanServices/localbackup.md)        |                                                                  |
 | `localsend`              | ❌ Removed                                                        |                                                                  |
-| `machine-id`             | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
-| `matrix-synapse`         | ✅ [Migrated](../../reference/clanServices/matrix-synapse.md)     |                                                                  |
+| `machine-id`             | ✅ [Migrated](/reference/clan.core/settings.md)              | Now an [option](/reference/clan.core/settings.md)           |
+| `matrix-synapse`         | ✅ [Migrated](/reference/clanServices/matrix-synapse.md)     |                                                                  |
 | `moonlight`              | ❌ Removed                                                        |                                                                  |
 | `mumble`                 | ❌ Removed                                                        |                                                                  |
-| `mycelium`               | ✅ [Migrated](../../reference/clanServices/mycelium.md)           |                                                                  |
+| `mycelium`               | ✅ [Migrated](/reference/clanServices/mycelium.md)           |                                                                  |
 | `nginx`                  | ❌ Removed                                                        |                                                                  |
-| `packages`               | ✅ [Migrated](../../reference/clanServices/packages.md)           |                                                                  |
-| `postgresql`             | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
-| `root-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              | See [migration guide](../../reference/clanServices/users.md#migration-from-root-password-module) |
+| `packages`               | ✅ [Migrated](/reference/clanServices/packages.md)           |                                                                  |
+| `postgresql`             | ✅ [Migrated](/reference/clan.core/settings.md)              | Now an [option](/reference/clan.core/settings.md)           |
+| `root-password`          | ✅ [Migrated](/reference/clanServices/users.md)              | See [migration guide](/reference/clanServices/users.md#migration-from-root-password-module) |
 | `single-disk`            | ❌ Removed                                                        |                                                                  |
-| `sshd`                   | ✅ [Migrated](../../reference/clanServices/sshd.md)               |                                                                  |
-| `state-version`          | ✅ [Migrated](../../reference/clan.core/settings.md)              | Now an [option](../../reference/clan.core/settings.md)           |
+| `sshd`                   | ✅ [Migrated](/reference/clanServices/sshd.md)               |                                                                  |
+| `state-version`          | ✅ [Migrated](/reference/clan.core/settings.md)              | Now an [option](/reference/clan.core/settings.md)           |
 | `static-hosts`           | ❌ Removed                                                        |                                                                  |
 | `sunshine`               | ❌ Removed                                                        |                                                                  |
 | `syncthing-static-peers` | ❌ Removed                                                        |                                                                  |
-| `syncthing`              | ✅ [Migrated](../../reference/clanServices/syncthing.md)          |                                                                  |
+| `syncthing`              | ✅ [Migrated](/reference/clanServices/syncthing.md)          |                                                                  |
 | `thelounge`              | ❌ Removed                                                        |                                                                  |
-| `trusted-nix-caches`     | ✅ [Migrated](../../reference/clanServices/trusted-nix-caches.md) |                                                                  |
-| `user-password`          | ✅ [Migrated](../../reference/clanServices/users.md)              |                                                                  |
+| `trusted-nix-caches`     | ✅ [Migrated](/reference/clanServices/trusted-nix-caches.md) |                                                                  |
+| `user-password`          | ✅ [Migrated](/reference/clanServices/users.md)              |                                                                  |
 | `vaultwarden`            | ❌ Removed                                                        |                                                                  |
 | `xfce`                   | ❌ Removed                                                        |                                                                  |
 | `zerotier-static-peers`  | ❌ Removed                                                        |                                                                  |
-| `zerotier`               | ✅ [Migrated](../../reference/clanServices/zerotier.md)           |                                                                  |
+| `zerotier`               | ✅ [Migrated](/reference/clanServices/zerotier.md)           |                                                                  |
 | `zt-tcp-relay`           | ❌ Removed                                                        |                                                                  |
 
 ---
@@ -378,6 +378,6 @@ instances = {
 
 ## Further reference
 
-* [Inventory Concept](../inventory/inventory.md)
-* [Authoring a 'clan.service' module](../services/community.md)
-* [ClanServices](../inventory/clanServices.md)
+* [Inventory Concept](/guides/inventory/inventory.md)
+* [Authoring a 'clan.service' module](/guides/services/community.md)
+* [ClanServices](/guides/inventory/clanServices.md)
diff --git a/docs/site/guides/migrations/migration-facts-vars.md b/docs/site/guides/migrations/migration-facts-vars.md
index 8f06ed38d..caf05c3ae 100644
--- a/docs/site/guides/migrations/migration-facts-vars.md
+++ b/docs/site/guides/migrations/migration-facts-vars.md
@@ -1,11 +1,11 @@
-# Migrate modules from `facts` to `vars`.
+# Migrate modules from `facts` to `vars`
 
 For a high level overview about `vars` see our [blog post](https://clan.lol/blog/vars/).
 
-This guide will help you migrate your modules that still use our [`facts`](../secrets.md) backend
-to the [`vars`](../vars/vars-overview.md) backend.
+This guide will help you migrate your modules that still use our [`facts`](/guides/migrations/migration-facts-vars.md) backend
+to the [`vars`](/guides/vars/vars-overview.md) backend.
 
-The `vars` [module](../../reference/clan.core/vars.md) and the clan [command](../../reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
+The `vars` [module](/reference/clan.core/vars.md) and the clan [command](/reference/cli/vars.md) work in tandem, they should ideally be kept in sync.
 
 ## Keep Existing Values
 
@@ -33,7 +33,6 @@ vars.generators.vaultwarden = {
 
 And this would read as follows: The vaultwarden `vars` module generates the admin file.
 
-
 ## Prompts
 
 Because prompts can be a necessity for certain systems `vars` have a shorthand for defining them.
@@ -46,7 +45,9 @@ facts.services.forgejo-api = {
     generator.script = "cp $prompt_value > $secret/token";
 };
 ```
+
 To have analogous functionality in `vars`:
+
 ```nix
 vars.generators.forgejo-api = {
     prompts.token = {
@@ -55,6 +56,7 @@ vars.generators.forgejo-api = {
     };
 };
 ```
+
 This does not only simplify prompting, it also now allows us to define multiple prompts in one generator.
 A more analogous way to the `fact` method is available, in case the module author needs more flexibility with the prompt input:
 
@@ -92,8 +94,8 @@ facts.services.syncthing = {
 };
 ```
 
-
 This would be the corresponding `vars` module, which also will migrate existing facts.
+
 ```nix
 vars.generators.syncthing = {
   migrateFact = "syncthing";
@@ -116,11 +118,11 @@ vars.generators.syncthing = {
   '';
 };
 ```
+
 Most of the usage patterns stay the same, but `vars` have a more ergonomic interface.
 There are not two different ways to define files anymore (public/secret).
 Now files are defined under the `files` attribute and are secret by default.
 
-
 ## Happy Migration
 
 We hope this gives you a clear path to start and finish your migration from `facts` to `vars`.
diff --git a/docs/site/guides/secrets.md b/docs/site/guides/secrets.md
index 14652e52e..c90b0a9cd 100644
--- a/docs/site/guides/secrets.md
+++ b/docs/site/guides/secrets.md
@@ -1,5 +1,5 @@
-This article provides an overview over the underlying secrets system which is used by [Vars](./vars/vars-overview.md).
-Under most circumstances you should use [Vars](./vars/vars-overview.md) directly instead.
+This article provides an overview over the underlying secrets system which is used by [Vars](/guides/vars/vars-overview.md).
+Under most circumstances you should use [Vars](/guides/vars/vars-overview.md) directly instead.
 
 Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
 
@@ -11,7 +11,7 @@ Clan enables encryption of secrets (such as passwords & keys) ensuring security
 
 By default, Clan uses the [sops](https://github.com/getsops/sops) format
 and integrates with [sops-nix](https://github.com/Mic92/sops-nix) on NixOS machines.
-Clan can also be configured to be used with other secret store [backends](../reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
+Clan can also be configured to be used with other secret store [backends](/reference/clan.core/vars.md#clan.core.vars.settings.secretStore).
 
 ## Create Your Admin Keypair
 
diff --git a/docs/site/guides/vars/vars-backend.md b/docs/site/guides/vars/vars-backend.md
index f3b22ad84..edae7df3b 100644
--- a/docs/site/guides/vars/vars-backend.md
+++ b/docs/site/guides/vars/vars-backend.md
@@ -1,6 +1,6 @@
 The `clan vars` subcommand is a powerful tool for managing machine-specific variables in a declarative and reproducible way. This guide will walk you through its usage, from setting up a generator to sharing and updating variables across machines.
 
-For a detailed API reference, see the [vars module documentation](../../reference/clan.core/vars.md).
+For a detailed API reference, see the [vars module documentation](/reference/clan.core/vars.md).
 
 In this guide, you will learn how to:
 
diff --git a/docs/site/guides/vars/vars-overview.md b/docs/site/guides/vars/vars-overview.md
index 8fd33edea..2eca03ec3 100644
--- a/docs/site/guides/vars/vars-overview.md
+++ b/docs/site/guides/vars/vars-overview.md
@@ -140,5 +140,5 @@ clan machines update my-machine
 
 ## Migration from Facts
 
-If you're currently using the legacy facts system, see our [Migration Guide](../migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
+If you're currently using the legacy facts system, see our [Migration Guide](/guides/migrations/migration-facts-vars.md) for step-by-step instructions on upgrading to vars.
 
diff --git a/docs/site/index.md b/docs/site/index.md
index 799d80c60..0c1d91f25 100644
--- a/docs/site/index.md
+++ b/docs/site/index.md
@@ -92,19 +92,19 @@ hide:
 
 <div class="grid cards" markdown>
 
--   [Inventory](./guides/inventory/inventory.md)
+-   [Inventory](/guides/inventory/inventory.md)
 
     ---
 
     Learn how about inventory
 
--   [Vars](./guides/vars/vars-overview.md)
+-   [Vars](/guides/vars/vars-overview.md)
 
     ---
 
     Learn how to use vars
 
--   [macOS](./guides/macos.md)
+-   [macOS](/guides/macos.md)
 
     ---
 
@@ -116,7 +116,7 @@ hide:
 
 <div class="grid cards" markdown>
 
--   [CLI](./reference/cli/index.md)
+-   [CLI](/reference/cli/index.md)
 
     ---
 
@@ -128,7 +128,7 @@ hide:
 
     Search all options
 
--   [Services](./reference/clanServices/index.md)
+-   [Services](/reference/clanServices/index.md)
 
     ---
 
diff --git a/lib/modules/clan/interface.nix b/lib/modules/clan/interface.nix
index c4b1830d0..1fd76ea83 100644
--- a/lib/modules/clan/interface.nix
+++ b/lib/modules/clan/interface.nix
@@ -237,7 +237,7 @@ in
       description = ''
         The `Inventory` submodule.
 
-        For details see the [Inventory](./inventory.md) documentation.
+        For details see the [Inventory](/reference/options/clan_inventory.md) documentation.
       '';
     };
 
diff --git a/lib/modules/inventoryClass/inventory.nix b/lib/modules/inventoryClass/inventory.nix
index 833de5f1b..339d8d44c 100644
--- a/lib/modules/inventoryClass/inventory.nix
+++ b/lib/modules/inventoryClass/inventory.nix
@@ -84,7 +84,7 @@ in
             - The module MUST have at least `features = [ "inventory" ]` in the frontmatter section.
             - The module MUST have a subfolder `roles` with at least one `{roleName}.nix` file.
 
-            For further information see: [Module Authoring Guide](../../guides/services/community.md).
+            For further information see: [Module Authoring Guide](/guides/services/community.md).
 
         ???+ example
             ```nix