From d25818580df5647c284a2c3b9974c60d612fe85e Mon Sep 17 00:00:00 2001 From: Qubasa Date: Tue, 16 Sep 2025 15:09:35 +0200 Subject: [PATCH] docs: Fixup stale references --- docs/mkdocs.yml | 66 ++++++++----------- docs/site/guides/disk-encryption.md | 2 +- .../guides/getting-started/add-machines.md | 4 +- .../guides/getting-started/add-services.md | 4 +- .../guides/getting-started/convert-flake.md | 2 +- .../getting-started/create-installer.md | 2 +- docs/site/guides/getting-started/update.md | 2 +- docs/site/guides/inventory/clanServices.md | 10 +-- docs/site/guides/inventory/inventory.md | 4 +- docs/site/guides/macos.md | 2 +- .../migrations/migrate-inventory-services.md | 8 +-- .../guides/migrations/migration-facts-vars.md | 4 +- docs/site/guides/secrets.md | 4 +- docs/site/guides/services/community.md | 2 +- docs/site/index.md | 6 +- 15 files changed, 57 insertions(+), 65 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index bfadef34b..ecc6238cd 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,5 +1,4 @@ site_name: Documentation -site_name: Documentation site_url: https://docs.clan.lol repo_url: https://git.clan.lol/clan/clan-core/ repo_name: "_>" @@ -63,13 +62,11 @@ nav: - Guides: - Inventory: - Introduction to Inventory: guides/inventory/inventory.md - - Minimal Example: guides/inventory/minimal-example.md + - File Autoincludes: guides/inventory/autoincludes.md - Clan Services: - - Introduction to Clan Services: guides/services/index.md - - Official Clan Services: guides/services/official.md - - Community Clan Services: guides/services/community.md - - Write Your Own Clan Service: guides/services/write-your-own.md + - Inventory Guide: guides/inventory/clanServices.md + - Author Your Own Service: guides/services/community.md - Vars: - Introduction to Vars: guides/vars/vars-overview.md - Minimal Example: guides/vars/vars-backend.md @@ -86,20 +83,12 @@ nav: - Introduction to Networking: guides/networking/networking.md - Zerotier VPN: guides/networking/mesh-vpn.md - Disko Templates: - - Introduction to Disko Templates: guides/disko-templates/index.md - - Official Disko Templates: guides/disko-templates/official.md - Community Disko Templates: guides/disko-templates/community.md - - Write Your Own Disko Template: guides/disko-templates/write-your-own.md - Backups: - Introduction to Backups: guides/backups.md - - Minimal Example: guides/backups/minimal.md - - Diving deeper: guides/backups/concepts.md - - Advanced Examples: guides/backups/advanced-examples.md - - Troubleshooting: guides/backups/troubleshooting.md - Flake-parts: guides/flake-parts.md - macOS: - - Introduction to macOS: guides/macos.md - - Example: guides/macos/example.md + - Managing macOS Machines: guides/macos.md # Should be part of the respective sections above # machines, disko, clan # - Templates: concepts/templates.md @@ -113,6 +102,9 @@ nav: - Hacking: guides/contributing/CONTRIBUTING.md - Advanced Debugging: guides/contributing/debugging.md - Testing: guides/contributing/testing.md + - Concepts: + - Templates: concepts/templates.md + - Reference: - Overview: reference/index.md - Clan Service API: reference/clanServices/clan-service-author-interface.md @@ -174,28 +166,28 @@ nav: - Services: - Introduction to ClanServices: reference/clanServices/index.md - Official: - - reference/clanServices/admin.md - - reference/clanServices/borgbackup.md - - reference/clanServices/certificates.md - - reference/clanServices/coredns.md - - reference/clanServices/data-mesher.md - - reference/clanServices/dyndns.md - - reference/clanServices/emergency-access.md - - reference/clanServices/garage.md - - reference/clanServices/hello-world.md - - reference/clanServices/importer.md - - reference/clanServices/localbackup.md - - reference/clanServices/matrix-synapse.md - - reference/clanServices/mycelium.md - - reference/clanServices/monitoring.md - - reference/clanServices/packages.md - - reference/clanServices/sshd.md - - reference/clanServices/syncthing.md - - reference/clanServices/trusted-nix-caches.md - - reference/clanServices/users.md - - reference/clanServices/wifi.md - - reference/clanServices/wireguard.md - - reference/clanServices/zerotier.md + - reference/clanServices/admin.md + - reference/clanServices/borgbackup.md + - reference/clanServices/certificates.md + - reference/clanServices/coredns.md + - reference/clanServices/data-mesher.md + - reference/clanServices/dyndns.md + - reference/clanServices/emergency-access.md + - reference/clanServices/garage.md + - reference/clanServices/hello-world.md + - reference/clanServices/importer.md + - reference/clanServices/localbackup.md + - reference/clanServices/matrix-synapse.md + - reference/clanServices/mycelium.md + - reference/clanServices/monitoring.md + - reference/clanServices/packages.md + - reference/clanServices/sshd.md + - reference/clanServices/syncthing.md + - reference/clanServices/trusted-nix-caches.md + - reference/clanServices/users.md + - reference/clanServices/wifi.md + - reference/clanServices/wireguard.md + - reference/clanServices/zerotier.md - Community: community/services/index.md - Clan Options: "/options" diff --git a/docs/site/guides/disk-encryption.md b/docs/site/guides/disk-encryption.md index f3bc619e7..7fd06e3ea 100644 --- a/docs/site/guides/disk-encryption.md +++ b/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](../guides/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](./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: diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index a26d60c5b..a6285cb98 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -2,11 +2,11 @@ Machines can be added using the following methods -- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../../concepts/autoincludes.md)) +- Create a file `machines/{machine_name}/configuration.nix` (See: [File Autoincludes](../inventory/autoincludes.md)) - Imperative via cli command: `clan machines create` - Editing nix expressions in flake.nix See [`clan-core.lib.clan`](/options/?scope=Flake Options (clan.nix file)) -See the complete [list](../../concepts/autoincludes.md) of auto-loaded files. +See the complete [list](../inventory/autoincludes.md) of auto-loaded files. ## Create a machine diff --git a/docs/site/guides/getting-started/add-services.md b/docs/site/guides/getting-started/add-services.md index 8c561059c..9d8dcb42f 100644 --- a/docs/site/guides/getting-started/add-services.md +++ b/docs/site/guides/getting-started/add-services.md @@ -10,7 +10,7 @@ In Clan Services are multi-Host & role-based: - You can use tags instead of explicit machine names. -To learn more: [Guide about clanService](../clanServices.md) +To learn more: [Guide about clanService](../inventory/clanServices.md) !!! Important It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe. @@ -41,7 +41,7 @@ To learn more: [Guide about clanService](../clanServices.md) ``` 1. See [reference/clanServices](../../reference/clanServices/index.md) for all available services and how to configure them. - Or read [authoring/clanServices](../../guides/services/community.md) if you want to bring your own + Or read [authoring/clanServices](../services/community.md) if you want to bring your own 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. diff --git a/docs/site/guides/getting-started/convert-flake.md b/docs/site/guides/getting-started/convert-flake.md index 30b0c54ac..ba269bbde 100644 --- a/docs/site/guides/getting-started/convert-flake.md +++ b/docs/site/guides/getting-started/convert-flake.md @@ -171,7 +171,7 @@ Clan needs to know where it can reach your hosts. For testing purpose set } ``` -See our guide on for properly [configuring machines networking](../networking.md) +See our guide on for properly [configuring machines networking](../networking/networking.md) ## Next Steps diff --git a/docs/site/guides/getting-started/create-installer.md b/docs/site/guides/getting-started/create-installer.md index 2476d014b..1f094eb98 100644 --- a/docs/site/guides/getting-started/create-installer.md +++ b/docs/site/guides/getting-started/create-installer.md @@ -152,7 +152,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](../../guides/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](../secure-boot.md) ## (Optional) Connect to Wifi Manually diff --git a/docs/site/guides/getting-started/update.md b/docs/site/guides/getting-started/update.md index 094c80422..8145e2d88 100644 --- a/docs/site/guides/getting-started/update.md +++ b/docs/site/guides/getting-started/update.md @@ -32,7 +32,7 @@ Ensure that the root login is secured and only used when necessary. ## Multiple Target Hosts -You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking.md). +You can now experiment with a new interface that allows you to define multiple `targetHost` addresses for different VPNs. Learn more and try it out in our [networking guide](../networking/networking.md). ## Updating Machine Configurations diff --git a/docs/site/guides/inventory/clanServices.md b/docs/site/guides/inventory/clanServices.md index 988a31a95..cd590a33f 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](../guides/services/community.md) +🔗 Learn how to write your own service: [Authoring a service](../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,7 @@ ______________________________________________________________________ ## What's Next? -- [Author your own clanService →](../guides/services/community.md) -- [Migrate from clanModules →](../guides/migrations/migrate-inventory-services.md) +- [Author your own clanService →](../services/community.md) +- [Migrate from clanModules →](../migrations/migrate-inventory-services.md) diff --git a/docs/site/guides/inventory/inventory.md b/docs/site/guides/inventory/inventory.md index 71db8b235..4659849f2 100644 --- a/docs/site/guides/inventory/inventory.md +++ b/docs/site/guides/inventory/inventory.md @@ -17,13 +17,13 @@ The following tutorial will walk through setting up a Backup service where the t ## Prerequisites -- [x] [Add some machines](../guides/getting-started/add-machines.md) to your Clan. +- [x] [Add some machines](../getting-started/add-machines.md) to your Clan. ## Services The inventory defines `instances` of clan services. Membership of `machines` is defined via `roles` exclusively. -See each [modules documentation](../reference/clanServices/index.md) for its available roles. +See each [modules documentation](../../reference/clanServices/index.md) for its available roles. ### Adding services to machines diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md index 8ab609e5a..8b388fd10 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](../guides/vars/vars-overview.md) +- Support for [vars](./vars/vars-overview.md) ## Add Your Machine to Your Clan Flake diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md index 4f64d5655..8c2c89059 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](../../guides/services/community.md) +If you are a **module author** and need to migrate your modules please consult our **new** [clanServices authoring guide](../services/community.md) ## What's Changing? @@ -378,6 +378,6 @@ instances = { ## Further reference -* [Inventory Concept](../../concepts/inventory.md) -* [Authoring a 'clan.service' module](../../guides/services/community.md) -* [ClanServices](../clanServices.md) +* [Inventory Concept](../inventory/inventory.md) +* [Authoring a 'clan.service' module](../services/community.md) +* [ClanServices](../inventory/clanServices.md) diff --git a/docs/site/guides/migrations/migration-facts-vars.md b/docs/site/guides/migrations/migration-facts-vars.md index f9c3323aa..8f06ed38d 100644 --- a/docs/site/guides/migrations/migration-facts-vars.md +++ b/docs/site/guides/migrations/migration-facts-vars.md @@ -2,8 +2,8 @@ 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`](../../guides/secrets.md) backend -to the [`vars`](../../guides/vars/vars-overview.md) backend. +This guide will help you migrate your modules that still use our [`facts`](../secrets.md) backend +to the [`vars`](../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. diff --git a/docs/site/guides/secrets.md b/docs/site/guides/secrets.md index 5d027de34..14652e52e 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](../guides/vars/vars-overview.md). -Under most circumstances you should use [Vars](../guides/vars/vars-overview.md) directly instead. +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. Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool. diff --git a/docs/site/guides/services/community.md b/docs/site/guides/services/community.md index 3ff012e96..ba2687feb 100644 --- a/docs/site/guides/services/community.md +++ b/docs/site/guides/services/community.md @@ -301,5 +301,5 @@ instnaces.machine-type = { ## Further Reading - [Reference Documentation for Service Authors](../../reference/clanServices/clan-service-author-interface.md) -- [Migration Guide from ClanModules to ClanServices](../../guides/migrations/migrate-inventory-services.md) +- [Migration Guide from ClanModules to ClanServices](../migrations/migrate-inventory-services.md) - [Decision that lead to ClanServices](../../decisions/01-ClanModules.md) diff --git a/docs/site/index.md b/docs/site/index.md index b12840ff6..5ab2e757a 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -12,13 +12,13 @@ hide:
-- [Inventory](./guides/inventory.md) +- [Inventory](./guides/inventory/inventory.md) --- Learn how about inventory -- [Vars](./guides/vars.md) +- [Vars](./guides/vars/vars-overview.md) --- @@ -48,7 +48,7 @@ hide: Search all options -- [Services](./reference/cli/index.md) +- [Services](./reference/clanServices/index.md) ---