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

This reverts commit d4305f8b3c.

docs/CONTRIBUTING.md

@@ -1,5 +1,4 @@
-# Contributing to Clan
+# Contributing
-
 
 **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.
 
@@ -95,40 +94,12 @@ 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)
 
-## Fixing Bugs or Adding Features in Clan-CLI
+### Whats 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.
+Please look into the [debugging](./debugging.md) guide next!
 
-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,19 +43,20 @@ exclude_docs: |
 nav:
   - Home: index.md
   - Getting Started:
-      - Setup Clan: getting-started/index.md
+      - Getting Started: getting-started/index.md
-      - Create Installer: getting-started/installer.md
+      - Installer: getting-started/installer.md
-      - Add Machines: getting-started/configure.md
+      - Configure: 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
-      - Vars Backend: manual/vars-backend.md
+      - Adding Machines: manual/adding-machines.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,4 +1,6 @@
-# Introduction to Backups
+# 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.
@@ -7,6 +9,8 @@ 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,3 +1,4 @@
+# Configuration - How to configure clan with your own machines
 
 Managing machine configurations can be done in the following ways:
 
@@ -207,3 +208,11 @@ 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,3 +1,4 @@
+# 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.
 
@@ -214,4 +215,12 @@ 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,3 +105,10 @@ 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 @@
-# Create an Installer Image
+# Installer
 
 Our installer image simplifies the process of performing remote installations.
 
@@ -197,3 +197,10 @@ 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,3 +1,4 @@
+# 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,3 +1,4 @@
+# Secrets / Facts
 
 Clan enables encryption of secrets (such as passwords & keys) ensuring security and ease-of-use among users.
 
@@ -83,3 +84,8 @@ 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  documentation
+# :material-home: Welcome to **Clan**'s awesome documentation
 
 [Getting Started](./getting-started/index.md){ .md-button }
 
-## Tutorials
+## What's inside
 
-**Learning-oriented adventures with a hands-on experience.**
+This documentation is structured into the following sections
 
 <div class="grid cards" markdown>
 
@@ -19,69 +19,25 @@ hide:
     ---
 
     Create your own clan and get everything
-    running in minutes
+    running in a couple of 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__
 
     ---
 
-    Create clanModules that can be reused by the community.
+    Instructions and explanations for practical Implementations ordered by Topic.
-
-    [: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,3 +1,4 @@
+# Adding Machines
 
 Clan has two general methods of adding machines:
 
@@ -17,18 +18,6 @@ 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,3 +1,4 @@
+# Debugging
 
 Here are some methods for debugging and testing the clan-cli
 
@@ -151,3 +152,6 @@ 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,3 +1,5 @@
+# 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,3 +1,4 @@
+# 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

@@ -0,0 +1,66 @@
+# :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,3 +1,4 @@
+# Inventory
 
 `Inventory` is an abstract service layer for consistently configuring distributed services across machine boundaries.
 

docs/site/manual/manage-root-password-via-vars.md

@@ -1,7 +1,4 @@
-
+# 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.
 

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. 
+This guide will help you migrate your existing Nix configurations into Clan. Keep
+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.
 
-!!! Warning
+!!! Danger
-    Migrating instead of starting new can be trickier and might lead to bugs or
+    **Back up your existing configuration!**
-    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.
+    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
-## Back up your existing configuration!
+    your configuration changes, it is also a good idea to follow the migration
-Before you start, it is strongly recommended to back up your existing
+    guide in a separte branch until everything works as expected.
-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,3 +1,4 @@
+# Repo Layout Guide
 
 This guide will help you navigate the codebase and locate key files:
 
@@ -23,3 +24,37 @@ $ 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),
+)
+```