Docs: add top-level index, refactor according to diataxis

clanModules/syncthing/README.md

@@ -19,7 +19,7 @@ We recommend configuring this module as an sync-service through the provided opt
 - **Share Folders**: Select folders to share with connected devices and configure permissions and synchronization parameters.
 
 !!! info
-    Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clan.syncthing.introducer)
+    Clan automatically discovers other devices. Automatic discovery requires one machine to be an [introducer](#clansyncthingintroducer)
 
     If that is not the case you can add the other device by its Device ID manually.
     You can find and share Device IDs under the "Add Device" button in the Web GUI. (`127.0.0.1:8384`)

docs/mkdocs.yml

@@ -39,24 +39,26 @@ exclude_docs: |
   /drafts/
 
 nav:
-  - Get Started:
+  - index.md
-      - index.md
-      - Installer: getting-started/installer.md
-      - Configure: getting-started/configure.md
-      - Secrets & Facts: getting-started/secrets.md
-      - Deploy Machine: getting-started/deploy.md
-      - Disk Encryption: getting-started/disk-encryption.md
-      - Mesh VPN: getting-started/mesh-vpn.md
-      - Backup & Restore: getting-started/backups.md
-      - Flake-parts: getting-started/flake-parts.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
+              - Disk Encryption: getting-started/disk-encryption.md
+              - Mesh VPN: getting-started/mesh-vpn.md
+              - Backup & Restore: getting-started/backups.md
+              - Flake-parts: getting-started/flake-parts.md
       - Include Machines: manual/include-machines.md
       - Inventory: manual/inventory.md
       - Secrets: manual/secrets.md
       - Secure Boot: manual/secure-boot.md
       - Contribute: manual/contribute.md
-  - Options:
+  - Reference:
       - Overview: reference/index.md
       - Clan Modules:
           - reference/clanModules/index.md

docs/nix/render_options/__init__.py

@@ -144,9 +144,8 @@ To use this module, import it like th:
 """
 
 
-clan_core_descr = """ClanCore delivers all the essential features for every clan.
+clan_core_descr = """`clan.core` is always included in each machine `config`.
-It's always included in your setup, and you can customize your clan's behavior with the configuration [options](#module-options) provided below.
+Your can customize your machines behavior with the configuration [options](#module-options) provided below.
-
 """
 
 options_head = "\n## Module Options\n"

docs/site/getting-started/configure.md

@@ -52,7 +52,7 @@ In the `flake.nix` file:
 
 === "**template using flake-parts**"
 
-    !!! info "See [Clan with flake-parts](./flake-parts.md) for help migrating to flake-parts."
+    !!! info "See [Clan with flake-parts](../manual/flake-parts.md) for help migrating to flake-parts."
 
     ```nix title="flake.nix" hl_lines="3"
     clan = {

docs/site/getting-started/deploy.md

@@ -77,7 +77,7 @@ This process involves preparing a suitable hardware and disk partitioning config
     │ │Onion address: 6evxy5yhzytwpnhc2vpscrbti3iktxdhpnf6yim6bbs25p4v6beemzyd.onion    │ │
     │ │Multicast DNS: nixos-installer.local                                             │ │
     │ └─────────────────────────────────────────────────────────────────────────────────┘ │
-    │ Press 'Ctrl-C' for console access                                                   │ 
+    │ Press 'Ctrl-C' for console access                                                   │
     │                                                                                     │
     └─────────────────────────────────────────────────────────────────────────────────────┘
     ```
@@ -100,7 +100,7 @@ This process involves preparing a suitable hardware and disk partitioning config
         ```
     2.  The root password for the installer medium.
         This password is autogenerated and meant to be easily typeable.
-    3.  See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi).
+    3.  See how to connect the installer medium to wlan [here](./installer.md#optional-connect-to-wifi-manually).
     4.  :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
         text__, images, ... basically anything that can be written in Markdown.
 

docs/site/getting-started/index.md

@@ -0,0 +1,109 @@
+# Getting Started
+
+Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository!
+
+### Prerequisites
+
+=== "**Linux**"
+
+    Clan depends on nix installed on your system. Run the following command to install nix.
+
+    ```bash
+    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+    ```
+
+    If you already have installed Nix, make sure you have the `nix-command` and `flakes` configuration enabled in your ~/.config/nix/nix.conf.
+    The determinate installer already comes with this configuration by default.
+
+    ```bash
+    # /etc/nix/nix.conf or ~/.config/nix/nix.conf
+    experimental-features = nix-command flakes
+    ```
+
+=== "**NixOS**"
+
+    If you run NixOS the `nix` binary is already installed.
+
+    You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
+
+    ```nix
+    { nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
+    ```
+
+=== "**Other**"
+
+    Clan doesn't offer dedicated support for other operating systems yet.
+
+### Step 1: Add Clan CLI to Your Shell
+
+Add the Clan CLI into your development workflow:
+
+```bash
+nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
+```
+
+You can find reference documentation for the `clan` cli program [here](../reference/cli/index.md).
+
+Alternatively you can check out the help pages directly:
+```terminalSession
+clan --help
+```
+
+### Step 2: Initialize Your Project
+
+Set the foundation of your Clan project by initializing it as follows:
+
+```bash
+clan flakes create my-clan
+```
+
+This command creates the `flake.nix` and `.clan-flake` files for your project.
+It will also generate files from a default template, to help show general clan usage patterns.
+
+### Step 3: Verify the Project Structure
+
+Ensure that all project files exist by running:
+
+```bash
+cd my-clan
+tree
+```
+
+This should yield the following:
+
+``` { .console .no-copy }
+.
+├── flake.nix
+├── machines
+│   ├── jon
+│   │   ├── configuration.nix
+│   │   └── hardware-configuration.nix
+│   └── sara
+│       ├── configuration.nix
+│       └── hardware-configuration.nix
+└── modules
+    └── shared.nix
+
+5 directories, 9 files
+```
+
+```bash
+clan machines list
+```
+
+``` { .console .no-copy }
+jon
+sara
+```
+
+!!! success
+
+    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/index.md

@@ -1,109 +1,38 @@
-# Setup
+# Home
 
-Create your own clan with these initial steps and manage a fleet of machines with one single testable git repository!
+## Welcome to **Clan**'s documentation
 
-### Prerequisites
+[Quickstart Guide](./getting-started/index.md){ .md-button }
 
-=== "**Linux**"
+## What's inside
 
-    Clan depends on nix installed on your system. Run the following command to install nix.
+This documentation is structured into the following sections
 
-    ```bash
+<div class="grid cards" markdown>
-    curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
-    ```
 
-    If you already have installed Nix, make sure you have the `nix-command` and `flakes` configuration enabled in your ~/.config/nix/nix.conf.
+-   :material-clock-fast:{ .lg .middle } __Set up in 15 minutes__
-    The determinate installer already comes with this configuration by default.
 
-    ```bash
+    ---
-    # /etc/nix/nix.conf or ~/.config/nix/nix.conf
-    experimental-features = nix-command flakes
-    ```
 
-=== "**NixOS**"
+    Create your own clan and get everything
+    running in a couple of minutes.
 
-    If you run NixOS the `nix` binary is already installed.
+    [:octicons-arrow-right-24: Getting started](./getting-started/index.md)
 
-    You will also need to enable the `flakes` and `nix-commands` experimental features in your configuration.nix:
+-   :material-sign-direction:{ .lg .middle } __Manual__
 
-    ```nix
+    ---
-    { nix.settings.experimental-features = [ "nix-command" "flakes" ]; }
-    ```
 
-=== "**Other**"
+    Instructions and explanations for practical Implementations ordered by Topic.
 
-    Clan doesn't offer dedicated support for other operating systems yet.
+    [:octicons-arrow-right-24: Manual](./manual/index.md)
 
-### Step 1: Add Clan CLI to Your Shell
+-   :material-api:{ .lg .middle } __Reference__
 
-Add the Clan CLI into your development workflow:
+    ---
 
-```bash
+    Detailed Specification of Functions and APIs.
-nix shell git+https://git.clan.lol/clan/clan-core#clan-cli
-```
 
-You can find reference documentation for the `clan` cli program [here](./reference/cli/index.md).
+    [:octicons-arrow-right-24: Reference](./reference/index.md)
 
-Alternatively you can check out the help pages directly:
+</div>
-```terminalSession
-clan --help
-```
-
-### Step 2: Initialize Your Project
-
-Set the foundation of your Clan project by initializing it as follows:
-
-```bash
-clan flakes create my-clan
-```
-
-This command creates the `flake.nix` and `.clan-flake` files for your project.
-It will also generate files from a default template, to help show general clan usage patterns.
-
-### Step 3: Verify the Project Structure
-
-Ensure that all project files exist by running:
-
-```bash
-cd my-clan
-tree
-```
-
-This should yield the following:
-
-``` { .console .no-copy }
-.
-├── flake.nix
-├── machines
-│   ├── jon
-│   │   ├── configuration.nix
-│   │   └── hardware-configuration.nix
-│   └── sara
-│       ├── configuration.nix
-│       └── hardware-configuration.nix
-└── modules
-    └── shared.nix
-
-5 directories, 9 files
-```
-
-```bash
-clan machines list
-```
-
-``` { .console .no-copy }
-jon
-sara
-```
-
-!!! success
-
-    You just successfully bootstrapped your first clan directory.
-
----
-
-### What's Next?
-
-- [**Installer**](getting-started/installer.md): Setting up new computers remotely is easy with an USB stick.
-
----

docs/site/manual/index.md

@@ -1,11 +1,34 @@
-# Manual
+# :material-book: Manual
 
-Explore the Clan Framework in detail with comprehensive information on specific topics:
+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)
+
+</div>
+
+## Guides
+
+**How-to Guides for achieving a certain goal or solving a specific issue.**
 
 - [Include Machines](./include-machines.md): Learn how Clan automatically includes machines and Nix files.
 
-- [Secrets](./secrets.md): Learn how you can manage secrets
+- [Secrets](./secrets.md): Learn how to manage secrets.
 
-- [Inventory](./inventory.md): Access a distributed and editable version of the NixOS module system.
+- [Inventory](./inventory.md): Distributed and editable version of the NixOS module system.
 
-- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!
+- [Flake-parts guide](./flake-parts.md): Use clan with [flake-parts](https://flake.parts/).
+
+- [Contribute](./contribute.md): Discover how to set up a development environment to contribute to Clan!

docs/site/reference/index.md

@@ -1,6 +1,20 @@
-This section of the site provides an automatically generated overview of the available options and commands within the Clan Framework.
+# :material-api: Overview
+
+This section of the site provides an **automatically extracted** overview of the available options and commands within the Clan Framework.
+
+---
 
 - Learn how to use the [Clan CLI](./cli/index.md)
 - Explore available services and application [modules](./clanModules/index.md)
 - Discover [configuration options](./clan-core/index.md) that manage essential features
-- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan
+- Find descriptions of the [Nix interfaces](./nix-api/index.md) for defining a Clan
+
+---
+
+!!! Note
+    This documentation is always built for the main branch.
+    If you need documentation for a specific commit you can build it on your own
+
+    ```bash
+    nix build 'git+https://git.clan.lol/clan/clan-core?ref=0324f4d4b87d932163f351e53b23b0b17f2b5e15#docs'
+    ```

lib/build-clan/interface.nix

@@ -8,7 +8,21 @@ in
     directory = lib.mkOption {
       type = types.path;
       default = self;
-      description = "The directory containing the clan subdirectory";
+      defaultText = "Root directory of the flake";
+      description = ''
+        The directory containing the clan.
+
+        A typical directory structure could look like this:
+
+        ```
+        .
+        ├── flake.nix
+        ├── assets
+        ├── machines
+        ├── modules
+        └── sops
+        ```
+      '';
     };
 
     specialArgs = lib.mkOption {