docs/mdbook: handle visible = "transparent"

[MattSturgeon]

Adds parity with NixOS/nixpkgs#441782 in our hacky manual docs logic.

See #4084 (comment)

There are probably some edge-cases this doesn't cover. I don't really want to invest too much time finding them when the right solution is to rip out our custom stuff and just use lib.options.optionAttrSetToDocList as intended.

One behaviour change is that internal = true is no longer considered when recursing into sub-options. This is intentional and matches how lib.options.optionAttrSetToDocList is implemented.

[khaneliman]

How is this supposed to be used? Adding to the example option, compiles the docs now, but it just hides the folding option entirely when i set it at the folding = mkOption level, if i put it in the submodule it doesn't do anything.

[MattSturgeon]

How is this supposed to be used? Adding to the example option, compiles the docs now, but it just hides the folding option entirely when i set it at the folding = mkOption level, if i put it in the submodule it doesn't do anything.

It is supposed to hide the option, but not its sub-options.

For folding, that'd mean folding is not documented but folding.enable is.

If it's not working, then that probably means some edge-cases with how isVisible is used on whole trees are coming back to bite us, which isn't too surprising.

[khaneliman]

Hmm yeah, for some reason I don't see enable documented

[MattSturgeon]

for some reason I don't see enable documented

Probably related to either, which doesn't implement getSubOptions.

Testing your PR merged in and this additional patch:

diff --git a/plugins/by-name/treesitter/default.nix b/plugins/by-name/treesitter/default.nix
index 1438e1fc..8bb3d655 100644
--- a/plugins/by-name/treesitter/default.nix
+++ b/plugins/by-name/treesitter/default.nix
@@ -162,8 +162,9 @@ lib.nixvim.plugins.mkNeovimPlugin {
       in
       mkOption {
         type = (types.either types.bool foldingSubmodule) // {
-          inherit (foldingSubmodule) description;
+          inherit (foldingSubmodule) description getSubOptions;
         };
+        visible = "transparent";
         default = {
           enable = false;
         };

And it seems to be working:

---

Yes, it's annoying that folding gets its own dedicated sub-page. Unfortunately that's just how our docs impl works; whenever we cross a suboptions boundary we fork into subpages. We also do this whenever options are nested more than one attr-level deep.

I could probably come up with something that avoids this when the submodule option is not visible, but it's hard to fully understand our docs impl which makes it hard to work on.

[khaneliman]

Alright, looks good knowing that merge needs to include getSubOptions for my use case.

[nixvim-ci]

Successfully created backport PR for nixos-25.11:

• [Backport nixos-25.11] docs/mdbook: handle visible = "transparent" #4093