docs: fix multiple format errors, improve readability of vars

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:

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/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
+     - The generator configuration
-   - Output of `clan --debug vars generate`
+
+     - The exact error message
+
+     - Output of `clan --debug vars generate`