Skip to content

docs(#3243): renderer.hidden_display help documentation is generated #3258

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alex-courtis merged 1 commit into from
Jan 31, 2026
+93 −62
Merged

docs(#3243): renderer.hidden_display help documentation is generated #3258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 43 additions & 45 deletions doc/nvim-tree-lua.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1808,50 +1808,6 @@ highlight group is not, hard linking as follows: >
NvimTreeLspDiagnosticsHintFolderText NvimTreeDiagnosticHintFolderHL
<

==============================================================================
Hidden Display *nvim-tree-hidden-display*

Show a summary of hidden files below the tree highlighted with `NvimTreeHiddenDisplay

Configure via |nvim_tree.config.renderer| {hidden_display}

*nvim_tree.config.renderer.hidden_display*
• `none`: disabled
• `simple`: show how many hidden files are in a folder
• `all`: show how many hidden and the number of hidden files by reason
• `fun(hidden_stats: table<string, integer>): string`: returns a summary of hidden stats

Example `"all"`:
If a folder has 14 hidden items for various reasons, the display might show: >
(14 total git: 5, dotfile: 9)
<
If a function is provided, it receives a table `hidden_stats` where keys are
reasons and values are the count of hidden files for that reason.

The `hidden_stats` argument is structured as follows, where <num> is the number
of hidden files related to the field: >
hidden_stats = {
bookmark = <num>,
buf = <num>,
custom = <num>,
dotfile = <num>,
git = <num>,
live_filter = <num>,
}
<
Example of function that can be passed: >lua
function(hidden_stats)
local total_count = 0
for reason, count in pairs(hidden_stats) do
total_count = total_count + count
end

if total_count > 0 then
return "(" .. tostring(total_count) .. " hidden)"
end
return nil
end
<

==============================================================================
Config *nvim-tree-config*
Expand Down Expand Up @@ -2104,6 +2060,19 @@ Config: renderer *nvim-tree-config-renderer*
end
<

{hidden_display} *nvim_tree.config.renderer.hidden_display*

Summary of hidden nodes, below the last node in the directory, highlighted
with `NvimTreeHiddenDisplay`.
• `"none"`: disabled, default
• `"simple"`: total number of hidden files e.g.
• (3 hidden)
• `"all"`: total and by reason: the filter that hid the node e.g.
• (14 total git: 5, dotfile: 9)
• `(fun(hidden_stats: nvim_tree.config.renderer.hidden_stats): string)`

See |nvim_tree.config.renderer.hidden_stats| for details and example.

Fields: ~
• {add_trailing}? (`boolean`, default: `false`) Appends a
trailing slash to folder and symlink folder
Expand All @@ -2121,7 +2090,7 @@ Config: renderer *nvim-tree-config-renderer*
• {indent_width}? (`integer`, default: `2`) Number of spaces
for each tree nesting level. Minimum 1.
• {hidden_display}? (`nvim_tree.config.renderer.hidden_display`, default: `none`)
|nvim-tree-hidden-display|
|nvim_tree.config.renderer.hidden_display|
• {symlink_destination}? (`boolean`, default: `true`) Appends an
arrow followed by the target of the
symlink.
Expand Down Expand Up @@ -2150,6 +2119,35 @@ Config: renderer *nvim-tree-config-renderer*
• {icons}? (`nvim_tree.config.renderer.icons`)
|nvim_tree.config.renderer.icons|

*nvim_tree.config.renderer.hidden_stats*
Number of hidden nodes in a directory by reason: the filter that hid the
node.

Passed to your |nvim_tree.config.renderer.hidden_display| function e.g. >lua

---@param hidden_stats nvim_tree.config.renderer.hidden_stats
---@return string? summary
local my_hidden_display = function(hidden_stats)
local total_count = 0
for reason, count in pairs(hidden_stats) do
total_count = total_count + count
end

if total_count > 0 then
return "(" .. tostring(total_count) .. " hidden)"
end
return nil
end
<

Fields: ~
• {bookmark} (`integer`)
• {buf} (`integer`)
• {custom} (`integer`)
• {dotfile} (`integer`)
• {git} (`integer`)
• {live_filter} (`integer`)

*nvim_tree.config.renderer.icons*
Icons and separators

Expand Down
57 changes: 48 additions & 9 deletions lua/nvim-tree/_meta/config/renderer.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,6 @@ error("Cannot require a meta file")



---@alias nvim_tree.config.renderer.highlight "none"|"icon"|"name"|"all"

---@alias nvim_tree.config.renderer.hidden_display "none"|"simple"|"all"|(fun(hidden_stats: table<string, integer>): string)

---@alias nvim_tree.config.renderer.icons.placement "before"|"after"|"signcolumn"|"right_align"



---Controls the appearance of the tree.
---
---See [nvim-tree-icons-highlighting] for {highlight_} and {decorators} fields.
Expand All @@ -24,6 +16,22 @@ error("Cannot require a meta file")
--- return ".../" .. vim.fn.fnamemodify(path, ":t")
---end
---```
---
---{hidden_display} [nvim_tree.config.renderer.hidden_display]()
---
---Summary of hidden nodes, below the last node in the directory, highlighted with `NvimTreeHiddenDisplay`.
---- `"none"`: disabled, default
---- `"simple"`: total number of hidden files e.g.
--- - (3 hidden)
---- `"all"`: total and by reason: the filter that hid the node e.g.
--- - (14 total git: 5, dotfile: 9)
---- `(fun(hidden_stats: nvim_tree.config.renderer.hidden_stats): string)`
---
---See [nvim_tree.config.renderer.hidden_stats] for details and example.
---@alias nvim_tree.config.renderer.hidden_display "none"|"simple"|"all"|(fun(hidden_stats: nvim_tree.config.renderer.hidden_stats): string?)
---
---@alias nvim_tree.config.renderer.highlight "none"|"icon"|"name"|"all"
---
---@class nvim_tree.config.renderer
---
---Appends a trailing slash to folder and symlink folder target names.
Expand All @@ -45,7 +53,7 @@ error("Cannot require a meta file")
---(default: `2`)
---@field indent_width? integer
---
---[nvim-tree-hidden-display]
---[nvim_tree.config.renderer.hidden_display]
---(default: `none`)
---@field hidden_display? nvim_tree.config.renderer.hidden_display
---
Expand Down Expand Up @@ -124,6 +132,9 @@ error("Cannot require a meta file")
---Icons and separators
---
---See [nvim-tree-icons-highlighting] for: {_placement} fields.
---
---@alias nvim_tree.config.renderer.icons.placement "before"|"after"|"signcolumn"|"right_align"
---
---@class nvim_tree.config.renderer.icons
---
---(default: `before`)
Expand Down Expand Up @@ -301,3 +312,31 @@ error("Cannot require a meta file")
---@field deleted? string
---(default: `"◌"`)
---@field ignored? string

---Number of hidden nodes in a directory by reason: the filter that hid the node.
---
---Passed to your [nvim_tree.config.renderer.hidden_display] function e.g.
---```lua
---
------@param hidden_stats nvim_tree.config.renderer.hidden_stats
------@return string? summary
---local my_hidden_display = function(hidden_stats)
--- local total_count = 0
--- for reason, count in pairs(hidden_stats) do
--- total_count = total_count + count
--- end
---
--- if total_count > 0 then
--- return "(" .. tostring(total_count) .. " hidden)"
--- end
--- return nil
---end
---```
---
---@class nvim_tree.config.renderer.hidden_stats
---@field bookmark integer
---@field buf integer
---@field custom integer
---@field dotfile integer
---@field git integer
---@field live_filter integer
5 changes: 1 addition & 4 deletions lua/nvim-tree/_meta/config/sort.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,6 @@ error("Cannot require a meta file")



---@alias nvim_tree.config.sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype"



---Sort files within a directory.
---
---{sorter} presets [nvim_tree.config.sort.Sorter]()
Expand All @@ -16,6 +12,7 @@ error("Cannot require a meta file")
---- `"extension"` uses all suffixes e.g. `foo.tar.gz` -> `.tar.gz`
---- `"suffix"` uses the last e.g. `foo.tar.gz` -> `.gz`
---- `"filetype"` [filetype]
---@alias nvim_tree.config.sort.Sorter "name"|"case_sensitive"|"modification_time"|"extension"|"suffix"|"filetype"
---
---{sorter} may be a function that is passed a list of `nvim_tree.api.Node` to be sorted in place e.g.
---```lua
Expand Down
5 changes: 1 addition & 4 deletions lua/nvim-tree/_meta/config/view.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,6 @@ error("Cannot require a meta file")



---@alias nvim_tree.config.view.width.spec string|integer|(fun(): integer|string)



---Configures the dimensions and appearance of the nvim-tree window.
---
---The window is "docked" at the left by default, however may be configured to float: [nvim_tree.config.view.float]
Expand All @@ -17,6 +13,7 @@ error("Cannot require a meta file")
---- `string`: `x%` string e.g. `30%`
---- `integer`: number of columns
---- `function`: returns one of the above
---@alias nvim_tree.config.view.width.spec string|integer|(fun(): integer|string)
---
---@class nvim_tree.config.view
---
Expand Down
Loading