yadunut/clan-core
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request 'docs: use absolute page URI' (#5368) from docs-simplify into main

Browse Source 
Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5368
This commit is contained in:
hsjobeki
2025-10-03 15:36:00 +00:00
parent cf8720e4dd 08c2d574ce
commit c04e8b6ead
15 changed files with 61 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/nix/render_options/__init__.py
View File

@@ -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.
"""

2
docs/site/getting-started/deploy-to-virtual-machine.md
View File

@@ -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`.

2
docs/site/guides/backups/backup-intro.md
View File

@@ -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:

2
docs/site/guides/contributing/debugging.md
View File

@@ -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

12
docs/site/guides/inventory/clanServices.md
View File

@@ -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)

2
docs/site/guides/macos.md
View File

@@ -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

2
docs/site/guides/migrations/disk-id.md
View File

@@ -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)

50
docs/site/guides/migrations/migrate-inventory-services.md
View File

@@ -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)

16
docs/site/guides/migrations/migration-facts-vars.md
View File

@@ -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`.

6
docs/site/guides/secrets.md
View File

@@ -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

2
docs/site/guides/vars/vars-backend.md
View File

@@ -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:

2
docs/site/guides/vars/vars-overview.md
View File

@@ -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.

10
docs/site/index.md
View File

@@ -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)
---

2
lib/modules/clan/interface.nix
View File

@@ -278,7 +278,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.
'';
};

2
lib/modules/inventoryClass/inventory.nix
View File

@@ -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