From 323a1784d3f4a11f80ebe58de97c5e7816e3d27f Mon Sep 17 00:00:00 2001 From: Alexander Courtis Date: Sat, 31 Jan 2026 15:29:03 +1100 Subject: [PATCH] docs(#3243): renderer.hidden_display help documentation is generated --- doc/nvim-tree-lua.txt | 88 ++++++++++++------------- lua/nvim-tree/_meta/config/renderer.lua | 57 +++++++++++++--- lua/nvim-tree/_meta/config/sort.lua | 5 +- lua/nvim-tree/_meta/config/view.lua | 5 +- 4 files changed, 93 insertions(+), 62 deletions(-) diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt index 0904c5c5106..725ab2d34f0 100644 --- a/doc/nvim-tree-lua.txt +++ b/doc/nvim-tree-lua.txt @@ -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`: 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 is the number -of hidden files related to the field: > - hidden_stats = { - bookmark = , - buf = , - custom = , - dotfile = , - git = , - live_filter = , - } -< -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* @@ -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 @@ -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. @@ -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 diff --git a/lua/nvim-tree/_meta/config/renderer.lua b/lua/nvim-tree/_meta/config/renderer.lua index 114a96d53a5..e1ba26cbb91 100644 --- a/lua/nvim-tree/_meta/config/renderer.lua +++ b/lua/nvim-tree/_meta/config/renderer.lua @@ -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) - ----@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. @@ -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. @@ -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 --- @@ -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`) @@ -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 diff --git a/lua/nvim-tree/_meta/config/sort.lua b/lua/nvim-tree/_meta/config/sort.lua index 255d9e1fe59..569fe56ba78 100644 --- a/lua/nvim-tree/_meta/config/sort.lua +++ b/lua/nvim-tree/_meta/config/sort.lua @@ -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]() @@ -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 diff --git a/lua/nvim-tree/_meta/config/view.lua b/lua/nvim-tree/_meta/config/view.lua index b526262a50d..bc599885593 100644 --- a/lua/nvim-tree/_meta/config/view.lua +++ b/lua/nvim-tree/_meta/config/view.lua @@ -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] @@ -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 ---