From 906cd9db2ddb5bc5e0f6647658fb4d42eefaa047 Mon Sep 17 00:00:00 2001
From: technofab <admin@technofab.de>
Date: Mon, 9 Feb 2026 19:42:17 +0100
Subject: [PATCH] docs: document importing nixlets

---
 docs/generating_docs.md | 16 ++++++++++++++++
 docs/importing.md       | 28 ++++++++++++++++++++++++++++
 nix/repo/docs.nix       |  1 +
 3 files changed, 45 insertions(+)
 create mode 100644 docs/importing.md

diff --git a/docs/generating_docs.md b/docs/generating_docs.md
index 9c4fc14..1ac80ba 100644
--- a/docs/generating_docs.md
+++ b/docs/generating_docs.md
@@ -11,6 +11,7 @@ This is all that's needed:
 ```nix
 (<nixlet>).mkDocs {
 # Params:
+#  fullValues ? false,
 #  transformOptions ? opt: opt,
 #  filter ? _: true,
 #  headingDepth ? 3,
@@ -36,3 +37,18 @@ string
 "Hello world!"
 ```
 ````
+
+The `fullValues` param controls whether the docs should include dependency Nixlets.
+For example, when defining `postgres` as a dependency, by default the docs would not
+include these options. If it's `true`, everything is included.
+
+Dependency Nixlets' options which you override from your own `values.nix` will show both
+default values:
+
+````md
+**Overridden value**:
+
+```nix
+<the overridden value set in values.nix>
+```
+````
diff --git a/docs/importing.md b/docs/importing.md
new file mode 100644
index 0000000..6bca353
--- /dev/null
+++ b/docs/importing.md
@@ -0,0 +1,28 @@
+# Importing Nixlets
+
+Nixlets can now define dependency Nixlets and handle them similarly to how nested
+Helm Charts work.
+
+## Importing
+
+To define a dependency Nixlet, give it a name and pass the Nixlet as a value:
+
+```nix title="default.nix of Nixlet"
+  nixlet.dependencies."postgres" = <any nixlet>;
+```
+
+`<any nixlet>` here could be stuff like `nixlet-lib.fetchNixletFromGitlab {...}`,
+`nixlet-lib.fetchNixlet <url> <sha>`, etc.
+
+## Defining Values
+
+You can pre-define values for dependency Nixlets like this:
+
+```nix title="values.nix of Nixlet"
+  options = {
+    # options for the current Nixlet
+  };
+  # overwriting the default of dependency Nixlets (the user can still overwrite this)
+  config."postgres".replicaCount = 10;
+```
+
diff --git a/nix/repo/docs.nix b/nix/repo/docs.nix
index 9d25c38..9199052 100644
--- a/nix/repo/docs.nix
+++ b/nix/repo/docs.nix
@@ -61,6 +61,7 @@ in
           {"Creating Nixlets" = "creation.md";}
           {"Packaging" = "packaging.md";}
           {"Usage" = "usage.md";}
+          {"Importing" = "importing.md";}
           {"Generating Docs" = "generating_docs.md";}
           {"Secrets" = "secrets.md";}
           {"Options" = "options.md";}