diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index aed48889a1..168c351d21 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -88,6 +88,7 @@ jobs:
             sed -i 's/\[output.linkcheck\]/#[output.linkcheck]/' docs/book.toml
             sh .github/completers.sh > docs/src/completers.md
             sh .github/macros.sh > docs/src/spec/macros.md
+            cmd/carapace/carapace --conditions=markdown > docs/src/variable/conditions.md
             mdbook build docs
             sh .github/badge.sh > docs/book/badge.svg
             sh .github/macros-badge.sh > docs/book/macros-badge.svg
diff --git a/cmd/carapace/cmd/root.go b/cmd/carapace/cmd/root.go
index 861b87a5fb..d1a53c919a 100644
--- a/cmd/carapace/cmd/root.go
+++ b/cmd/carapace/cmd/root.go
@@ -64,13 +64,16 @@ var rootCmd = &cobra.Command{
 	ValidArgs: completers.Names(),
 	Run: func(cmd *cobra.Command, args []string) {
 		// since flag parsing is disabled do this manually
+		// TODO switch to cobra flag parsing with interspersed=false (redirect completion from completers/carapace_completer to here)
 		switch args[0] {
 		case "--conditions":
 			if len(args) > 1 {
 				//printCondition(args[1]) // TODO
 			} else {
-				printConditions() // TODO
+				fmt.Fprintln(cmd.OutOrStdout(), printConditions("yaml-short")) // TODO
 			}
+		case "--conditions=markdown":
+			fmt.Fprintln(cmd.OutOrStdout(), printConditions("markdown")) // TODO
 		case "--macros":
 			if len(args) > 1 {
 				printMacro(args[1])
@@ -309,11 +312,22 @@ func printCompletersJson() {
 	}
 }
 
-func printConditions() {
-	// TODO marshal ordered using yaml
-	for name, macro := range conditions.MacroMap {
-		fmt.Printf("%v: %#v\n", name, macro.Description)
+func printConditions(format string) string {
+	s := make([]string, 0)
+	switch format {
+	case "yaml-short":
+		// TODO marshal ordered using yaml
+		for name, macro := range conditions.MacroMap {
+			s = append(s, fmt.Sprintf("%v: %#v", name, macro.Description))
+		}
+
+	case "markdown":
+		s = append(s, "# Conditions", "")
+		for name, macro := range conditions.MacroMap {
+			s = append(s, fmt.Sprintf("- [%v](https://pkg.go.dev/github.com/rsteube/carapace-bin/pkg/conditions#Condition%v) %v", name, name, macro.Description))
+		}
 	}
+	return strings.Join(s, "\n")
 }
 
 func printMacros() {
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 642a478557..20b89d24ea 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -16,7 +16,8 @@
     - [Examples](./spec/examples.md)
     - [Macros](./spec/macros.md)
   - [Overlay](./overlay.md)
-  - [Environment](./environment.md)
+  - [Variable](./variable.md)
+    - [Conditions](./variable/conditions.md)
   - [Development](./development.md)
     - [Build](./development/build.md)
     - [docker-compose](./development/docker-compose.md)
diff --git a/docs/src/environment-condition.cast b/docs/src/variable-condition.cast
similarity index 100%
rename from docs/src/environment-condition.cast
rename to docs/src/variable-condition.cast
diff --git a/docs/src/environment-custom.cast b/docs/src/variable-custom.cast
similarity index 100%
rename from docs/src/environment-custom.cast
rename to docs/src/variable-custom.cast
diff --git a/docs/src/environment.cast b/docs/src/variable.cast
similarity index 100%
rename from docs/src/environment.cast
rename to docs/src/variable.cast
diff --git a/docs/src/environment.md b/docs/src/variable.md
similarity index 88%
rename from docs/src/environment.md
rename to docs/src/variable.md
index dcb98cd1bd..d400d5982a 100644
--- a/docs/src/environment.md
+++ b/docs/src/variable.md
@@ -1,4 +1,4 @@
-# Environment
+# Variable
 
 > feature in development
 
@@ -9,7 +9,7 @@ For other shells custom functions are added.
 
 > Setting `CARAPACE_ENV=0` before sourcing `carapace _carapace` disables this behaviour.
 
-![](./environment.cast)
+![](./variable.cast)
 
 ## Custom variables
 
@@ -27,7 +27,7 @@ completion:
     HTTPS_PROXY: ["https://localhost:8443\tdevelopment", "https://proxy.company:443\tproduction"]
 ```
 
-![](./environment-custom.cast)
+![](./variable-custom.cast)
 
 It is also possible to define conditions.
 
@@ -40,6 +40,4 @@ completion:
     CUSTOM_CONDITION: ["within", "git", "repo"]
 ```
 
-![](./environment-condition.cast)
-
-> TODO document conditions
\ No newline at end of file
+![](./variable-condition.cast)
diff --git a/docs/src/variable/conditions.md b/docs/src/variable/conditions.md
new file mode 100644
index 0000000000..96dfc1d239
--- /dev/null
+++ b/docs/src/variable/conditions.md
@@ -0,0 +1,3 @@
+# Conditions
+
+_filled automatically_