Merge pull request 'docs: fix multiple format errors, improve readability of vars' (#5142) from Qubasa/clan-core:improve_vars_docs into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5142

docs/mkdocs.yml

@@ -61,8 +61,6 @@ nav:
           - Continuous Integration: guides/getting-started/flake-check.md
           - Convert Existing NixOS Config: guides/getting-started/convert-flake.md
       - ClanServices: guides/clanServices.md
-      - Backup & Restore: guides/backups.md
-      - Disk Encryption: guides/disk-encryption.md
       - Vars:
           - Overview: guides/vars-overview.md
           - Getting Started: guides/vars-backend.md
@@ -70,6 +68,8 @@ nav:
           - Advanced Examples: guides/vars-advanced-examples.md
           - Troubleshooting: guides/vars-troubleshooting.md
       - Age Plugins: guides/age-plugins.md
+      - Backup & Restore: guides/backups.md
+      - Disk Encryption: guides/disk-encryption.md
       - Secrets management: guides/secrets.md
       - Networking: guides/networking.md
       - Zerotier VPN: guides/mesh-vpn.md
@@ -89,7 +89,6 @@ nav:
           - Disk id: guides/migrations/disk-id.md
   - Concepts:
       - Inventory: concepts/inventory.md
-      - Generators: concepts/generators.md
       - Autoincludes: concepts/autoincludes.md
       - Templates: concepts/templates.md
   - Reference:
@@ -224,4 +223,4 @@ plugins:
   - redoc-tag
   - redirects:
       redirect_maps:
-        guides/getting-started/secrets.md: concepts/generators.md
+        guides/getting-started/secrets.md: guides/vars-overview.md

docs/site/concepts/generators.md

@@ -1,45 +0,0 @@
-# Generators
-
-Generators are the core mechanism of the clan vars system for automating the creation and management of generated files, especially secrets, in your NixOS configurations.
-
-## What are Generators?
-
-Generators solve a common problem: instead of manually running commands like `mkpasswd` to create password hashes and copying them into your configuration, generators automate this process declaratively.
-
-A generator defines:
-
-- **Input prompts**: Values to request from users (passwords, names, etc.)
-- **Generation script**: Logic to transform inputs into outputs
-- **Output files**: Generated files that can be secrets or public data
-- **Dependencies**: Other generators this one depends on
-- **Runtime inputs**: Tools and packages needed by the script
-
-## Key Benefits
-
-- **Reproducible**: Same inputs produce same outputs across machines
-- **Declarative**: Defined in your NixOS configuration alongside usage
-- **Secure**: Automatic handling of secrets storage and deployment
-- **Collaborative**: Shared generators work across team environments
-- **Automated**: No manual copy-paste of generated values
-
-## Common Use Cases
-
-- **Password hashing**: Generate secure password hashes for user accounts
-- **SSH keys**: Create and manage SSH host and user keys
-- **Certificates**: Generate TLS certificates and certificate authorities
-- **API tokens**: Create secure random tokens for services
-- **Configuration files**: Generate config files that depend on secrets
-
-## Learning Path
-
-1. **Start here**: [Vars Getting Started Guide](../guides/vars-backend.md) - Hands-on tutorial with practical examples
-2. **Understand the architecture**: [Vars Concepts Guide](../guides/vars-concepts.md) - Deep dive into design principles and patterns
-3. **Explore complex scenarios**: [Advanced Examples](../guides/vars-advanced-examples.md) - Real-world patterns and best practices
-4. **Troubleshoot issues**: [Troubleshooting Guide](../guides/vars-troubleshooting.md) - Common problems and solutions
-
-## API Reference
-
-For complete configuration options and technical details, see:
-
-- [Vars NixOS Module Reference](../reference/clan.core/vars.md) - All configuration options
-- [Vars CLI Reference](../reference/cli/vars.md) - Command-line interface

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](../concepts/generators.md)
+- Support for [vars](../guides/vars-overview.md)
 
 ## Add Your Machine to Your Clan Flake
 

docs/site/guides/migrations/migration-facts-vars.md

@@ -3,7 +3,7 @@
 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`](../../concepts/generators.md) backend.
+to the [`vars`](../../guides/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.
 

docs/site/guides/secrets.md

@@ -1,5 +1,5 @@
-This article provides an overview over the underlying secrets system which is used by [Vars](../concepts/generators.md).
+This article provides an overview over the underlying secrets system which is used by [Vars](../guides/vars-overview.md).
-Under most circumstances you should use [Vars](../concepts/generators.md) directly instead.
+Under most circumstances you should use [Vars](../guides/vars-overview.md) directly instead.
 
 Consider using `clan secrets` only for managing admin users and groups, as well as a debugging tool.
 
@@ -292,15 +292,14 @@ The following diagrams illustrates how a user can provide a secret (i.e. a Passw
 
 ```plantuml
 @startuml
-!include C4_Container.puml
 
-Person(user, "User", "Someone who manages secrets")
+actor "User" as user
-ContainerDb(secret, "Secret")
+database "Secret" as secret
-Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
+rectangle "Machine" as machine
 
-Rel_R(user, secret, "Encrypt", "", "Pubkeys: User, Machine")
+user -right-> secret : Encrypt\n(Pubkeys: User, Machine)
-Rel_L(secret, user, "Decrypt", "",  "user privkey")
+secret -left-> user : Decrypt\n(user privkey)
-Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
+secret -right-> machine : Decrypt\n(machine privkey)
 
 @enduml
 ```
@@ -316,19 +315,18 @@ Common use cases:
 
 ```plantuml
 @startuml
-!include C4_Container.puml
 
-System_Boundary(c1, "Group") {
+rectangle "Group" {
-    Person(user1, "User A", "has access")
+    actor "User A" as user1
-    Person(user2, "User B", "has access")
+    actor "User B" as user2
 }
 
-ContainerDb(secret, "Secret")
+database "Secret" as secret
-Container(machine, "Machine", "A Machine. i.e. Needs the Secret for a given Service." )
+rectangle "Machine" as machine
-
-Rel_R(c1, secret, "Encrypt", "", "Pubkeys: User A, User B, Machine")
-Rel_R(secret, machine, "Decrypt", "", "machine privkey" )
 
+user1 -right-> secret : Encrypt
+user2 -right-> secret : (Pubkeys: User A, User B, Machine)
+secret -right-> machine : Decrypt\n(machine privkey)
 
 @enduml
 ```
@@ -347,19 +345,17 @@ Common use cases:
 
 ```plantuml
 @startuml
-!include C4_Container.puml
-!include C4_Deployment.puml
 
-Person(user, "User", "Someone who manages secrets")
+actor "User" as user
-ContainerDb(secret, "Secret")
+database "Secret" as secret
-System_Boundary(c1, "Group") {
+rectangle "Group" {
-    Container(machine1, "Machine A", "Both machines need the same secret" )
+    rectangle "Machine A" as machine1
-    Container(machine2, "Machine B", "Both machines need the same secret" )
+    rectangle "Machine B" as machine2
 }
 
-Rel_R(user, secret, "Encrypt", "", "Pubkeys: machine A, machine B, User")
+user -right-> secret : Encrypt\n(Pubkeys: machine A, machine B, User)
-Rel(secret, c1, "Decrypt", "", "Both machine A or B can decrypt using their private key" )
+secret -down-> machine1 : Decrypt
-
+secret -down-> machine2 : (Both machines can decrypt\nusing their private key)
 
 @enduml
 ```

docs/site/guides/vars-advanced-examples.md

@@ -1,6 +1,7 @@
 # Advanced Vars Examples
 
-This guide demonstrates complex, real-world patterns for the vars system. For basic usage, see the [Getting Started guide](vars-backend.md).
+This guide demonstrates complex, real-world patterns for the vars system. 
+
 
 ## Certificate Authority with Intermediate Certificates
 

docs/site/guides/vars-backend.md

@@ -1,27 +1,19 @@
+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.
 
-!!! Note
+For a detailed API reference, see the [vars module documentation](../reference/clan.core/vars.md).
-    This guide demonstrates the vars system for managing secrets and generated files
 
+In this guide, you will learn how to:
 
-Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration.
+1. Declare a `generator` in the machine's NixOS configuration.
+2. Inspect the status of variables using the Clan CLI.
+3. Generate variables interactively.
+4. Observe the changes made to your repository.
+5. Update the machine configuration.
+6. Share the root password between multiple machines.
+7. Change the root password when needed.
 
-In this example, we will guide you through automating that interaction using clan `vars`.
+By the end of this guide, you will have a clear understanding of how to use `clan vars` to manage sensitive data, such as passwords, in a secure and efficient manner.
 
-For architectural concepts and design principles, see the [Concepts guide](vars-concepts.md). For the complete API reference, see the [vars module documentation](../reference/clan.core/vars.md).
-
-This guide assumes
-- Clan is set up already (see [Getting Started](../guides/getting-started/index.md))
-- a machine has been added to the clan (see [Adding Machines](getting-started/add-machines.md))
-
-This section will walk you through the following steps:
-
-1. declare a `generator` in the machine's nixos configuration
-2. inspect the status via the Clan CLI
-3. generate the vars
-4. observe the changes
-5. update the machine
-6. share the root password between machines
-7. change the password
 
 ## Declare the generator
 
@@ -144,12 +136,3 @@ Updated var root-password/password-hash
   new: $6$OyoQtDVzeemgh8EQ$zRK...
 ```
 
-
-## Further Reading
-
-- [Understanding Vars Concepts](vars-concepts.md) - Learn about the architecture and core concepts
-- [Advanced Examples](vars-advanced-examples.md) - Complex real-world examples including certificates, SSH keys, and more
-- [Troubleshooting Guide](vars-troubleshooting.md) - Common issues and solutions
-- [Migration Guide](migrations/migration-facts-vars.md) - Migrate from legacy facts system
-- [Reference Documentation for `clan.core.vars` NixOS options](../reference/clan.core/vars.md)
-- [Reference Documentation for the `clan vars` CLI command](../reference/cli/vars.md)

docs/site/guides/vars-concepts.md

@@ -1,6 +1,6 @@
 # Understanding Clan Vars - Concepts & Architecture
 
-This guide explains the architecture and design principles behind the vars system. For a hands-on tutorial, see the [Getting Started guide](vars-backend.md).
+This guide explains the architecture and design principles behind the vars system. 
 
 ## Architecture Overview
 
@@ -121,9 +121,3 @@ Compared to manual secret management, vars provides:
 - **User prompts**: Gather input when needed
 - **Easy regeneration**: Update secrets with a single command
 
-## Next Steps
-
-- [Practical Tutorial](vars-backend.md) - Step-by-step guide
-- [Advanced Examples](vars-advanced-examples.md) - Real-world patterns
-- [Troubleshooting](vars-troubleshooting.md) - Common issues
-- [Reference](../reference/clan.core/vars.md) - Complete API

docs/site/guides/vars-overview.md

@@ -16,9 +16,13 @@ users.users.root.hashedPasswordFile = "/tmp/root-password-hash";
 ```
 
 This approach has several problems:
+
 - **Not reproducible**: Manual steps vary between team members
+
 - **Hard to maintain**: Updating secrets requires remembering manual commands  
+
 - **Deployment friction**: Secrets must be managed outside of your configuration
+
 - **Team collaboration issues**: Sharing credentials securely is complex
 
 ### After Vars: Declarative Generation
@@ -85,46 +89,21 @@ The vars system has three main components:
 
 ### 1. **Generators**
 Define how to create files from inputs:
+
 - **Prompts**: Values requested from users
+
 - **Scripts**: Generation logic  
+
 - **Dependencies**: Other generators this depends on
+
 - **Outputs**: Files that get created
 
 ### 2. **Storage Backends**
 Handle secret storage and deployment:
+
 - **sops**: Encrypted files in git (recommended)
+
 - **password-store**: GPG/age-based secret storage
-- **vm**: For development/testing
-
-### 3. **Integration**
-Seamless NixOS integration:
-- File paths available at build time
-- Automatic deployment to machines
-- Service restarts on changes
-
-## Learning Path
-
-Ready to get started? Follow this recommended path:
-
-### 1. **🚀 Hands-On Tutorial**
-[Vars Getting Started Guide](vars-backend.md)
-Start here for a practical walkthrough with password generation.
-
-### 2. **🏗️ Understand the Design**  
-[Vars Concepts & Architecture](vars-concepts.md)
-Deep dive into design principles and advanced patterns.
-
-### 3. **💡 Real-World Examples**
-[Advanced Examples](vars-advanced-examples.md)
-Complex scenarios including certificates, SSH keys, and databases.
-
-### 4. **🔧 Troubleshooting**
-[Troubleshooting Guide](vars-troubleshooting.md)
-Solutions for common issues and debugging techniques.
-
-### 5. **📚 Complete Reference**
-- [NixOS Module Options](../reference/clan.core/vars.md)
-- [CLI Commands](../reference/cli/vars.md)
 
 ## Quick Start Example
 
@@ -164,6 +143,3 @@ clan machines update my-machine
 
 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.
 
----
-
-**Ready to start?** Head to the [Getting Started Guide](vars-backend.md) for your first hands-on experience with the vars system.

docs/site/guides/vars-troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting Vars
 
-Quick reference for diagnosing and fixing vars issues. For basic usage, see the [Getting Started guide](vars-backend.md).
+Quick reference for diagnosing and fixing vars issues.
 
 ## Common Issues
 
@@ -240,8 +240,11 @@ clan vars list my-machine
 **Solution**: Ensure your user/machine has the correct age keys configured. Clan manages encryption keys automatically based on the configured users and machines in your flake.
 
 Check that:
+
 1. Your machine is properly configured in the flake
+  
 2. Your user has access to the machine's secrets
+   
 3. The age key is available in the expected location
 
 ### Password Store Issues
@@ -261,6 +264,9 @@ If these solutions don't resolve your issue:
 1. Check the [clan-core issue tracker](https://git.clan.lol/clan/clan-core/issues)
 2. Ask in the Clan community channels
 3. Provide:
+  
      - The generator configuration
+
      - The exact error message
+
      - Output of `clan --debug vars generate`

docs/site/index.md

@@ -55,7 +55,7 @@ Explore the underlying principles of Clan
 
 <div class="grid cards" markdown>
 
--   [Generators](./concepts/generators.md)
+-   [Vars](./guides/vars-overview.md)
 
     ---