From f584d1d70d36cd29d45abce91776f8425398a97f Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Wed, 29 Jan 2025 22:01:00 +0000
Subject: [PATCH] docs/mdbook: support `visible = "shallow"`

---
 docs/mdbook/default.nix | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/docs/mdbook/default.nix b/docs/mdbook/default.nix
index 3224b0e1..2c2e6775 100644
--- a/docs/mdbook/default.nix
+++ b/docs/mdbook/default.nix
@@ -35,18 +35,31 @@ let
   removeWhitespace = builtins.replaceStrings [ " " ] [ "" ];
 
   getSubOptions =
-    opts: path: lib.optionalAttrs (isVisible opts) (removeUnwanted (opts.type.getSubOptions path));
+    opts: path:
+    lib.optionalAttrs (isDeeplyVisible opts) (removeUnwanted (opts.type.getSubOptions path));
 
-  isVisible =
-    opts:
+  isVisible = isVisibleWith true;
+  isDeeplyVisible = isVisibleWith false;
+
+  isVisibleWith =
+    shallow: opts:
+    let
+      test =
+        opt:
+        let
+          internal = opt.internal or false;
+          visible = opt.visible or true;
+          visible' = if visible == "shallow" then shallow else visible;
+        in
+        visible' && !internal;
+    in
     if lib.isOption opts then
-      opts.visible or true && !(opts.internal or false)
+      test opts
     else if opts.isOption then
-      opts.index.options.visible or true && !(opts.index.options.internal or false)
+      test opts.index.options
     else
       let
-        filterFunc = lib.filterAttrs (_: v: if lib.isAttrs v then isVisible v else true);
-
+        filterFunc = lib.filterAttrs (_: v: if lib.isAttrs v then isVisibleWith shallow v else true);
         hasEmptyIndex = (filterFunc opts.index.options) == { };
         hasEmptyComponents = (filterFunc opts.components) == { };
       in