Docs: restructure apply diataxis

docs/.gitignore

@@ -1,6 +1,3 @@
-/site/reference/clan-core
-/site/reference/clanModules
-/site/reference/nix-api/inventory.md
-/site/reference/cli
+/site/reference
 /site/static/Roboto-Regular.ttf
 /site/static/FiraCode-VF.ttf

docs/mkdocs.yml

@@ -40,24 +40,27 @@ exclude_docs: |
 
 nav:
   - index.md
-  - Manual:
-      - Overview: manual/index.md
-      - Tutorials:
   - Getting Started:
       - getting-started/index.md
       - Installer: getting-started/installer.md
       - Configure: getting-started/configure.md
       - Secrets & Facts: getting-started/secrets.md
       - Deploy Machine: getting-started/deploy.md
+  - Guides:
+      - Overview: manual/index.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
+      - Machines: manual/include-machines.md
       - Inventory: manual/inventory.md
       - Secrets: manual/secrets.md
       - Secure Boot: manual/secure-boot.md
       - Flake-parts: manual/flake-parts.md
+      - Authoring ClanModules:
+          - clanmodules/index.md
       - Contribute: manual/contribute.md
+  - Concepts:
+      - Overview: concepts/index.md
   - Reference:
       - Overview: reference/index.md
       - Clan Modules:
@@ -119,7 +122,6 @@ nav:
           - reference/clan-core/deployment.md
           - reference/clan-core/networking.md
       - Nix API:
-          - reference/nix-api/index.md
           - buildClan: reference/nix-api/buildclan.md
           - Inventory: reference/nix-api/inventory.md
   - Blog:

docs/site/clanmodules/index.md

@@ -0,0 +1,7 @@
+# Authoring a clanModule
+
+This site will guide you through authoring your first module. Explaining which conventions must be followed, such that others will have an enjoyable experience and the module can be used with minimal effort.
+
+:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
+Under construction
+:fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:

docs/site/concepts/index.md

@@ -0,0 +1,3 @@
+# Core Concepts
+
+TODO

docs/site/getting-started/secrets.md

@@ -60,5 +60,4 @@ If you followed the quickstart tutorial all necessary secrets are initialized at
 ## Whats next?
 
 - [Deployment](deploy.md): How to remotely deploy your machine
-- [Advanced Secrets](../manual/secrets.md) If you want to know more about how to save and share passwords in your clan 
-
+- 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

@@ -1,8 +1,14 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
 # Home
 
 ## Welcome to **Clan**'s documentation
 
-[Quickstart Guide](./getting-started/index.md){ .md-button }
+[Getting Started](./getting-started/index.md){ .md-button }
 
 ## What's inside
 
@@ -19,13 +25,21 @@ This documentation is structured into the following sections
 
     [:octicons-arrow-right-24: Getting started](./getting-started/index.md)
 
--   :material-sign-direction:{ .lg .middle } __Manual__
+-   :simple-abstract:{ .lg .middle } __Concepts__
+
+    ---
+
+    Important Core Concepts that should be inderstood to get the best experience.
+
+    [:octicons-arrow-right-24: Core Concepts](./concepts/index.md)
+
+-   :material-sign-direction:{ .lg .middle } __Guides__
 
     ---
 
     Instructions and explanations for practical Implementations ordered by Topic.
 
-    [:octicons-arrow-right-24: Manual](./manual/index.md)
+    [:octicons-arrow-right-24: Guides](./manual/index.md)
 
 -   :material-api:{ .lg .middle } __Reference__
 

docs/site/manual/index.md

@@ -17,18 +17,50 @@ Instructions and explanations for practical Implementations ordered by Topics.
 
     [: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.**
 
-- [Adding Machines](./adding-machines.md): Learn how Clan automatically includes machines and Nix files.
+<div class="grid cards" markdown>
 
-- [Secrets](./secrets.md): Learn how to manage secrets.
+-   [Machines](./include-machines.md)
 
-- [Inventory](./inventory.md): Clan's declaration format for running **services** on one or multiple **machines**.
+    ---
 
-- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/).
+    Learn how Clan automatically includes machines and Nix files.
 
-- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!
+-   [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/reference/nix-api/buildclan.md

@@ -1,29 +1,170 @@
-# buildClan
+# BuildClan
 
-The core [function](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/default.nix) that produces a Clan. It returns a set of consistent configurations for all machines with ready-to-use secrets, backups and other services.
+This provides an overview of the available arguments of the `buildClan` function.
 
-## Inputs
+!!! Note "Flake-parts"
+    Each attribute is also available via `clan.<option>`
 
-`directory`
-: The directory containing the machines subdirectory
+    For example `clan.inventory = ...;` is equivalent to `buildClan { inventory = ...; }`.
 
-`machines`
-: Allows to include machine-specific modules i.e. machines.${name} = { ... }
 
-`meta`
-: An optional set
+### directory
 
-: `{ name :: string, icon :: string, description :: string }`
 
-`inventory`
-: Service set for easily configuring distributed services, such as backups
 
-: For more details see [Inventory](./inventory.md)
 
-`specialArgs`
-: Extra arguments to pass to nixosSystem i.e. useful to make self available
 
-`pkgsForSystem`
-: A function that maps from architecture to pkgs, if specified this nixpkgs will be only imported once for each system.
-  This improves performance, but all nipxkgs.* options will be ignored.
-  `(string -> pkgs )`
+The directory containing the clan.
+
+A typical directory structure could look like this:
+
+```
+.
+├── flake.nix
+├── assets
+├── machines
+├── modules
+└── sops
+```
+
+buildClan argument: `directory`
+
+
+**Type**: `path`
+
+
+**Default**:
+
+```nix
+"Root directory of the flake"
+```
+        
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### inventory
+
+
+
+
+
+The `Inventory` submodule.
+
+For details see the [Inventory](./inventory.md) documentation.
+
+
+**Type**: `submodule`
+
+
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### machines
+
+
+
+
+
+A mapping of machine names to their nixos configuration.
+
+???+ example
+
+    ```nix
+    machines = {
+      my-machine = {
+        # Your nixos configuration
+      };
+    };
+    ```
+
+
+**Type**: `module`
+
+
+**Default**:
+
+```nix
+{ }
+```
+        
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### meta
+
+
+
+
+
+Global information about the clan.
+
+
+**Type**: `null or (submodule)`
+
+
+**Default**:
+
+```nix
+null
+```
+        
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### meta.name
+
+
+
+
+
+Needs to be (globally) unique, as this determines the folder name where the flake gets downloaded to.
+
+**Type**: `null or string`
+
+
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### pkgsForSystem
+
+
+
+
+
+A function that maps from architecture to pkg. `( string -> pkgs )`
+
+If specified this nixpkgs will be only imported once for each system.
+This improves performance, but all nipxkgs.* options will be ignored.
+
+
+**Type**: `function that evaluates to a(n) (null or (attribute set))`
+
+
+**Default**:
+
+```nix
+"Lambda :: String -> { ... } | null"
+```
+        
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+
+
+### specialArgs
+
+
+
+
+
+Extra arguments to pass to nixosSystem i.e. useful to make self available
+
+**Type**: `attribute set of raw value`
+
+
+**Default**:
+
+```nix
+{ }
+```
+        
+:simple-git: [interface.nix](https://git.clan.lol/clan/clan-core/src/branch/main/lib/build-clan/interface.nix)
+

docs/site/reference/nix-api/index.md

@@ -1,6 +0,0 @@
-# Nix API Overview
-
-There are two top-level components of the Nix API, which together allow for the declarative definition of a Clan:
-
-- the [Inventory](./inventory.md), a structure representing the machines, services, custom configurations, and other data that constitute a Clan, and
-- the [`buildClan`](./buildclan.md) function, which constructs a Clan from an Inventory definition.