Reapply "docs: Document imports dir. Remove What's next sections everywhere. Merge guide overview and hompage view."

This reverts commit b19beb8913.

docs/CONTRIBUTING.md

@@ -1,4 +1,5 @@
-# Contributing
+# Contributing to Clan
+
 
 **Continuous Integration (CI)**: Each pull request gets automatically tested by gitea. If any errors are detected, it will block pull requests until they're resolved.
 
@@ -94,12 +95,40 @@ Let's get your development environment up and running:
       merge-after-ci --reviewers Mic92 Lassulus Qubasa
       ```
 
+## Related Projects
 
+- **Data Mesher**: [dm](https://git.clan.lol/clan/dm)
+- **Nixos Facter**: [nixos-facter](https://github.com/nix-community/nixos-facter)
+- **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere)
+- **Disko**: [disko](https://github.com/nix-community/disko)
 
-### Whats Next?
+## Fixing Bugs or Adding Features in Clan-CLI
 
-Please look into the [debugging](./debugging.md) guide next!
+If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup.
 
+For instance, if you need to update `nixos-anywhere` in clan-cli, find its usage:
+
+```python
+run(
+    nix_shell(
+        ["nixpkgs#nixos-anywhere"],
+        cmd,
+    ),
+    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
+)
+```
+
+You can replace `"nixpkgs#nixos-anywhere"` with your local path:
+
+```python
+run(
+    nix_shell(
+        ["<path_to_local_src>#nixos-anywhere"],
+        cmd,
+    ),
+    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
+)
+```
 
 # Standards
 

docs/mkdocs.yml

@@ -43,20 +43,19 @@ exclude_docs: |
 nav:
   - Home: index.md
   - Getting Started:
-      - Getting Started: getting-started/index.md
+      - Setup Clan: getting-started/index.md
-      - Installer: getting-started/installer.md
+      - Create Installer: getting-started/installer.md
-      - Configure: getting-started/configure.md
+      - Add Machines: getting-started/configure.md
       - Secrets & Facts: getting-started/secrets.md
       - Deploy Machine: getting-started/deploy.md
   - Guides:
-      - Overview: manual/index.md
-      - Manage passwords using vars: manual/manage-root-password-via-vars.md
       - Disk Encryption: getting-started/disk-encryption.md
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
-      - Adding Machines: manual/adding-machines.md
+      - Vars Backend: manual/vars-backend.md
+      - Facts Backend: manual/secrets.md
+      - Autoincludes: manual/adding-machines.md
       - Inventory: manual/inventory.md
-      - Secrets: manual/secrets.md
       - Secure Boot: manual/secure-boot.md
       - Flake-parts: manual/flake-parts.md
       - Authoring:

docs/site/getting-started/backups.md

@@ -1,6 +1,4 @@
-# Backups
+# Introduction to Backups
-
-## Introduction to Backups
 
 When you're managing your own services, creating regular backups is crucial to ensure your data's safety.
 This guide introduces you to Clan's built-in backup functionalities.
@@ -9,8 +7,6 @@ We might add more options in the future, but for now, let's dive into how you ca
 
 ## Backing Up Locally with Localbackup
 
-### What is Localbackup?
-
 Localbackup lets you backup your data onto physical storage devices connected to your computer,
 such as USB hard drives or network-attached storage. It uses a tool called rsnapshot for this purpose.
 

docs/site/getting-started/configure.md

@@ -1,4 +1,3 @@
-# Configuration - How to configure clan with your own machines
 
 Managing machine configurations can be done in the following ways:
 
@@ -208,11 +207,3 @@ If you only want to setup a single machine at this point, you can delete `sara`
 ```
 git rm ./machines/sara
 ```
-
----
-
-## What's next?
-
-- [Secrets & Facts](secrets.md): Setting up secrets with sops-nix
-
----

docs/site/getting-started/deploy.md

@@ -1,4 +1,3 @@
-# Deploy Machine
 
 Integrating a new machine into your Clan environment is an easy yet flexible process, allowing for a straight forward management of multiple NixOS configurations.
 
@@ -215,12 +214,4 @@ buildClan {
 
 This is useful for machines that are not always online or are not part of the regular update cycle.
 
----
-
-## What's next ?
-
-- [**Disk Encryption**](./disk-encryption.md): Configure disk encryption with remote decryption
-- [**Mesh VPN**](./mesh-vpn.md): Configuring a secure mesh network.
-
----
 

docs/site/getting-started/index.md

@@ -105,10 +105,3 @@ sara
 
     You just successfully bootstrapped your first clan directory.
 
----
-
-### What's Next?
-
-- [**Installer**](./installer.md): Setting up new computers remotely is easy with an USB stick.
-
----

docs/site/getting-started/installer.md

@@ -1,4 +1,4 @@
-# Installer
+# Create an Installer Image
 
 Our installer image simplifies the process of performing remote installations.
 
@@ -197,10 +197,3 @@ Press ++ctrl+d++ to exit `IWD`.
 
 You're all set up
 
----
-
-## What's next?
-
-- [Configure Machines](configure.md): Customize machine configuration
-
----

docs/site/getting-started/mesh-vpn.md

@@ -1,4 +1,3 @@
-# Mesh VPN
 
 This guide provides detailed instructions for configuring
 [ZeroTier VPN](https://zerotier.com) within Clan. Follow the

docs/site/getting-started/secrets.md

@@ -1,4 +1,3 @@
-# Secrets / Facts
 
 Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
 
@@ -84,8 +83,3 @@ This command helps ensure that your system configuration is correct and free fro
 
     You can integrate this step into your [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) workflow to ensure that only valid Nix configurations are merged into your codebase.
 
-
-## What's next?
-
-- [Deployment](deploy.md): How to remotely deploy your machine
-- Full [Secrets](../manual/secrets.md) guide If you want to know more about how to save and share passwords in your clan

docs/site/index.md

@@ -4,13 +4,13 @@ hide:
   - toc
 ---
 
-# :material-home: Welcome to **Clan**'s awesome documentation
+# :material-home: Welcome to **Clan**'s  documentation
 
 [Getting Started](./getting-started/index.md){ .md-button }
 
-## What's inside
+## Tutorials
 
-This documentation is structured into the following sections
+**Learning-oriented adventures with a hands-on experience.**
 
 <div class="grid cards" markdown>
 
@@ -19,25 +19,69 @@ This documentation is structured into the following sections
     ---
 
     Create your own clan and get everything
-    running in a couple of minutes.
+    running in minutes
 
     [:octicons-arrow-right-24: Getting started](./getting-started/index.md)
 
-
+-   :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__
--   :material-sign-direction:{ .lg .middle } __Guides__
 
     ---
 
-    Instructions and explanations for practical Implementations ordered by Topic.
+    Create clanModules that can be reused by the community.
+
+    [:octicons-arrow-right-24: Authoring clanModules](./clanmodules/index.md)
+
+</div>
+
+## :material-book: Guides
+
+**How-to Guides for achieving a certain goal or solving a specific issue.**
+
+<div class="grid cards" markdown>
+
+-   [Autoincludes](./manual/adding-machines.md)
+
+    ---
+
+    Learn how Clan automatically includes machines and Nix files.
+
+-   [Vars Backend](./manual/vars-backend.md)
+
+    ---
+
+    Learn how to manage secrets with facts.
+
+-   [Inventory](./manual/inventory.md)
+
+    ---
+
+    Clan's declaration format for running **services** on one or multiple **machines**.
+
+-   [Flake-parts](./manual/flake-parts.md)
+
+    ---
+
+    Use clan with [https://flake-parts.dev]()
+
+-   [Contribute](./manual/contribute.md)
+
+    ---
+
+    Discover how to set up a development environment to contribute to Clan!
+
+</div>
+
+## API Reference
+
+**Auto generated API Documentation**
+
+<div class="grid cards" markdown>
+
+-   [Reference Overview](./reference/index.md)
+
+    ---
+
+    Learn how to interface with Clan programmatically
 
-    [:octicons-arrow-right-24: Guides](./manual/index.md)
-
--   :material-api:{ .lg .middle } __Reference__
-
-    ---
-
-    Detailed Specification of Functions and APIs.
-
-    [:octicons-arrow-right-24: Reference](./reference/index.md)
 
 </div>

docs/site/manual/adding-machines.md

@@ -1,4 +1,3 @@
-# Adding Machines
 
 Clan has two general methods of adding machines:
 
@@ -18,6 +17,18 @@ Every folder `machines/{machineName}` will be registered automatically as a Clan
     - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/)
     - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md).
 
+
+## Automatic Imports
+
+The `buildClan` function will automatically import modules if a directory named `<CLAN_ROOT>/imports` exists within the Clan. Below are the conditions for importing inventory modules:
+
+- **Inventory Modules**: Modules located in `<CLAN_ROOT>/imports/inventory` will be automatically imported. Note that only inventory-compatible modules can be used in this location. To be compatible, a module must contain a `roles` folder. 
+
+- **Adding a Module**: To add a module, such as `mymodule`, create a dedicated directory at `<CLAN_ROOT>/imports/inventory/mymodule`, ensuring that it includes a `roles` folder.
+
+For further details on creating Clan modules, please refer to the [Authoring Clan Modules](../clanmodules/index.md) section. 
+
+
 ## Manual declaration
 
 Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../manual/inventory.md).

docs/site/manual/debugging.md

@@ -1,4 +1,3 @@
-# Debugging
 
 Here are some methods for debugging and testing the clan-cli
 
@@ -152,6 +151,3 @@ If you need to inspect the Nix sandbox while running tests, follow these steps:
 
 Or you can also use the [nix breakpoint hook](https://nixos.org/manual/nixpkgs/stable/#breakpointhook)
 
-### What's next?
-
-Please look into the [repo layout](./repo-layout.md) guide next!

docs/site/manual/disk-templates.md

@@ -1,5 +1,3 @@
-# Disk Templates
-
 
 !!! Danger ":fontawesome-solid-road-barrier: Under Construction :fontawesome-solid-road-barrier:"
     Currently under construction use with caution

docs/site/manual/flake-parts.md

@@ -1,4 +1,3 @@
-# Clan with `flake-parts`
 
 Clan supports integration with [flake.parts](https://flake.parts/) a tool which allows composing nixos modules in a modular way.
 

docs/site/manual/index.md

@@ -1,66 +0,0 @@
-# :material-book: Guides
-
-Instructions and explanations for practical Implementations ordered by Topics.
-
-## Tutorials
-
-**Learning-oriented adventures with a hands-on experience.**
-
-<div class="grid cards" markdown>
-
--   :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__
-
-    ---
-
-    Create your own clan and get everything
-    running in minutes
-
-    [:octicons-arrow-right-24: Getting started](../getting-started/index.md)
-
--   :fontawesome-solid-user-group:{ .lg .middle } __Authoring Modules__
-
-    ---
-
-    Create clanModules that can be reused by the community.
-
-    [:octicons-arrow-right-24: Authoring clanModules](../clanmodules/index.md)
-
-</div>
-
-## Guides
-
-**How-to Guides for achieving a certain goal or solving a specific issue.**
-
-<div class="grid cards" markdown>
-
--   [Machines](./adding-machines.md)
-
-    ---
-
-    Learn how Clan automatically includes machines and Nix files.
-
--   [Secrets](./secrets.md)
-
-    ---
-
-    Learn how to manage secrets.
-
--   [Inventory](./inventory.md)
-
-    ---
-
-    Clan's declaration format for running **services** on one or multiple **machines**.
-
--   [Flake-parts](./flake-parts.md)
-
-    ---
-
-    Use clan with [https://flake-parts.dev]()
-
--   [Contribute](./contribute.md)
-
-    ---
-
-    Discover how to set up a development environment to contribute to Clan!
-
-</div>

docs/site/manual/inventory.md

@@ -1,4 +1,3 @@
-# Inventory
 
 `Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
 

docs/site/manual/migration-guide.md

@@ -1,16 +1,16 @@
 # Migrate existing NixOS configurations
 
-This guide will help you migrate your existing Nix configurations into Clan. Keep
+This guide will help you migrate your existing Nix configurations into Clan. 
-in mind, though, this approach can be trickier and might lead to bugs or
-unexpected issues. We recommend following the Getting Started guide first. Once
-you have a working setup, you can easily transfer your Nix configurations over.
 
-!!! Danger
+!!! Warning
-    **Back up your existing configuration!**
+    Migrating instead of starting new can be trickier and might lead to bugs or
-    Before you start, it is strongly recommended to back up your existing
+    unexpected issues. We recommend following the [Getting Started](../getting-started/index.md) guide first. Once you have a working setup, you can easily transfer your Nix configurations over.
-    configuration in any form you see fit. If you use version control to manage
+
-    your configuration changes, it is also a good idea to follow the migration
+## Back up your existing configuration!
-    guide in a separte branch until everything works as expected.
+Before you start, it is strongly recommended to back up your existing
+configuration in any form you see fit. If you use version control to manage
+your configuration changes, it is also a good idea to follow the migration
+guide in a separte branch until everything works as expected.
 
 
 ## Starting Point

docs/site/manual/repo-layout.md

@@ -1,4 +1,3 @@
-# Repo Layout Guide
 
 This guide will help you navigate the codebase and locate key files:
 
@@ -24,37 +23,3 @@ $ tree -L 1
 
 To dive into infrastructure, check out our clan infra repo: [clan-infra](https://git.clan.lol/clan/clan-infra). Please provide us with your public SOPS key so we can add you as an admin.
 
-## Related Projects
-
-- **Data Mesher**: [dm](https://git.clan.lol/clan/dm)
-- **Nixos Facter**: [nixos-facter](https://github.com/nix-community/nixos-facter)
-- **Nixos Anywhere**: [nixos-anywhere](https://github.com/nix-community/nixos-anywhere)
-- **Disko**: [disko](https://github.com/nix-community/disko)
-
-## Fixing Bugs or Adding Features in Clan-CLI
-
-If you have a bug fix or feature that involves a related project, clone the relevant repository and replace its invocation in your local setup.
-
-For instance, if you need to update `nixos-anywhere` in clan-cli, find its usage:
-
-```python
-run(
-    nix_shell(
-        ["nixpkgs#nixos-anywhere"],
-        cmd,
-    ),
-    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
-)
-```
-
-You can replace `"nixpkgs#nixos-anywhere"` with your local path:
-
-```python
-run(
-    nix_shell(
-        ["<path_to_local_src>#nixos-anywhere"],
-        cmd,
-    ),
-    RunOpts(log=Log.BOTH, prefix=machine.name, needs_user_terminal=True),
-)
-```

docs/site/manual/vars-backend.md

@@ -1,4 +1,7 @@
-# Managing the root password declaratively using `vars`
+
+!!! Note
+    Vars is the new secret backend that will soon replace the Facts backend
+
 
 Defining a linux user's password via the nixos configuration previously required running `mkpasswd ...` and then copying the hash back into the nix configuration.