From 5c746311c7a0641dccb253ee529b4d57518ccb9e Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 29 Jul 2025 16:50:48 +0200
Subject: [PATCH] templates: init docs

---
 docs/mkdocs.yml                 |  1 +
 docs/site/concepts/templates.md | 69 +++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 docs/site/concepts/templates.md

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 6c333c6c9..eb52100fb 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -81,6 +81,7 @@ nav:
       - Inventory: concepts/inventory.md
       - Generators: concepts/generators.md
       - Autoincludes: concepts/autoincludes.md
+      - Templates: concepts/templates.md
   - Reference:
       - Overview: reference/index.md
       - Clan Options: options.md
diff --git a/docs/site/concepts/templates.md b/docs/site/concepts/templates.md
new file mode 100644
index 000000000..8f1c35243
--- /dev/null
+++ b/docs/site/concepts/templates.md
@@ -0,0 +1,69 @@
+# How Templates work
+
+Clan offers the ability to use templates for creating different resources.
+It comes with some `<builtin>` templates and discovers all exposed templates from its flake's `inputs`
+
+For example one can list all current templates like this:
+
+```shellSession
+$ clan templates list
+Available 'clan' templates
+├── <builtin>
+│   ├── default: Initialize a new clan flake
+│   ├── flake-parts: Flake-parts
+│   └── minimal: for clans managed via (G)UI
+└── inputs.self:
+    ├── default: Initialize a new clan flake
+    ├── flake-parts: Flake-parts
+    └── minimal: for clans managed via (G)UI
+Available 'disko' templates
+├── <builtin>
+│   └── single-disk: A simple ext4 disk with a single partition
+└── inputs.self:
+    └── single-disk: A simple ext4 disk with a single partition
+Available 'machine' templates
+├── <builtin>
+│   ├── demo-template: Demo machine for the CLAN project
+│   ├── flash-installer: Initialize a new flash-installer machine
+│   ├── new-machine: Initialize a new machine
+│   └── test-morph-template: Morph a machine
+└── inputs.self:
+    ├── demo-template: Demo machine for the CLAN project
+    ├── flash-installer: Initialize a new flash-installer machine
+    ├── new-machine: Initialize a new machine
+    └── test-morph-template: Morph a machine
+```
+
+## Using `<builtin>` Templates
+
+Templates are referenced via the `--template` `selector`
+
+clan-core ships its native/builtin templates. Those are referenced if the selector is a plain string ( without `#` or `./.` )
+
+For example:
+
+`clan flakes create --template=flake-parts`
+
+would use the native `<builtin>.flake-parts` template
+
+## Selectors follow nix flake `reference#attribute` syntax
+
+Selectors follow a very similar pattern as Nix's native attribute selection behavior.
+
+Just like `nix build .` would build `packages.x86-linux.default` of the flake in `./.`
+
+`clan flakes create --template=.` would create a clan from your **local** `default` clan template (`templates.clan.default`).
+
+In fact this command would be equivalent, just make it more explicit
+
+`clan flakes create --template=.#clan.templates.clan.default` (explicit path)
+
+## Remote templates
+
+Just like with Nix you could specify a remote url or path to the flake containing the template
+
+`clan flakes create --template=github:owner/repo#foo`
+
+!!! Note "Implementation Note"
+    Not all features of Nix's attribute selection are currently matched.
+    There are minor differences in case of unexpected behavior please create an [issue](https://git.clan.lol/clan/clan-core/issues/new)