Skip to content

Commit d0a1426

Browse files
alex-courtisalex-courtis
committed
docs(#3088): unify help and readme, clarify some wording
1 parent 033bfd3 commit d0a1426

5 files changed

Lines changed: 113 additions & 77 deletions

File tree

‎README.md‎

Lines changed: 99 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -32,50 +32,55 @@ Questions and general support: [Discussions](https://github.com/nvim-tree/nvim-t
3232

3333
[nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons) is optional and used to display file icons. It requires a [patched font](https://www.nerdfonts.com/). Your terminal emulator must be configured to use that font, usually "Hack Nerd Font"
3434

35-
## Install
35+
## Installing
3636

37-
Please install via your preferred package manager. See [Installation](https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation) for specific package manager instructions.
38-
39-
`nvim-tree/nvim-tree.lua`
37+
Please install via your preferred package manager. See [Installation](https://github.com/nvim-tree/nvim-tree.lua/wiki/Installation) for some specific package manager instructions.
4038

4139
Major or minor versions may be specified via tags: `v<MAJOR>` e.g. `v1` or `v<MAJOR>.<MINOR>` e.g. `v1.23`
4240

43-
`nvim-tree/nvim-web-devicons` optional, for file icons
41+
## Quick Start
4442

45-
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
43+
Install the plugins via your package manager:
44+
`"nvim-tree/nvim-tree.lua"`
45+
`"nvim-tree/nvim-web-devicons"`
4646

47-
## Quick Start
47+
Disabling [netrw](https://neovim.io/doc/user/pi_netrw.html) is strongly advised, see [:help nvim-tree-netrw](doc/nvim-tree-lua.txt)
4848

4949
### Setup
5050

51-
Setup the plugin in your `init.lua`
51+
Setup the plugin in your `init.lua`.
52+
53+
See [:help nvim-tree-setup](doc/nvim-tree-lua.txt) and [:help nvim-tree-config-default](doc/nvim-tree-lua.txt)
5254

5355
```lua
54-
-- disable netrw at the very start of your init.lua
55-
vim.g.loaded_netrw = 1
56-
vim.g.loaded_netrwPlugin = 1
57-
58-
-- optionally enable 24-bit colour
59-
vim.opt.termguicolors = true
60-
61-
-- empty setup using defaults
62-
require("nvim-tree").setup()
63-
64-
-- OR setup with some options
65-
require("nvim-tree").setup({
66-
sort = {
67-
sorter = "case_sensitive",
68-
},
69-
view = {
70-
width = 30,
71-
},
72-
renderer = {
73-
group_empty = true,
74-
},
75-
filters = {
76-
dotfiles = true,
77-
},
78-
})
56+
-- disable netrw at the very start of your init.lua
57+
vim.g.loaded_netrw = 1
58+
vim.g.loaded_netrwPlugin = 1
59+
60+
-- optionally enable 24-bit colour
61+
vim.opt.termguicolors = true
62+
63+
-- empty setup using defaults
64+
require("nvim-tree").setup()
65+
66+
-- OR setup with a config
67+
68+
---@type nvim_tree.config
69+
local config = {
70+
sort = {
71+
sorter = "case_sensitive",
72+
},
73+
view = {
74+
width = 30,
75+
},
76+
renderer = {
77+
group_empty = true,
78+
},
79+
filters = {
80+
dotfiles = true,
81+
},
82+
}
83+
require("nvim-tree").setup(config)
7984
```
8085

8186
### Help
@@ -86,62 +91,91 @@ Show the mappings: `g?`
8691

8792
### Custom Mappings
8893

89-
[:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via |nvim-tree.on_attach| e.g.
94+
[:help nvim-tree-mappings-default](doc/nvim-tree-lua.txt) are applied by default however you may customise via [:help nvim_tree.config](doc/nvim-tree-lua.txt) `{on_attach}` e.g.
9095

9196
```lua
92-
local function my_on_attach(bufnr)
93-
local api = require "nvim-tree.api"
97+
local function my_on_attach(bufnr)
98+
local api = require "nvim-tree.api"
9499

95-
local function opts(desc)
96-
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
97-
end
100+
local function opts(desc)
101+
return { desc = "nvim-tree: " .. desc, buffer = bufnr, noremap = true, silent = true, nowait = true }
102+
end
98103

99-
-- default mappings
100-
api.map.on_attach.default(bufnr)
104+
-- default mappings
105+
api.map.on_attach.default(bufnr)
101106

102-
-- custom mappings
103-
vim.keymap.set('n', '<C-t>', api.tree.change_root_to_parent, opts('Up'))
104-
vim.keymap.set('n', '?', api.tree.toggle_help, opts('Help'))
105-
end
107+
-- custom mappings
108+
vim.keymap.set("n", "<C-t>", api.tree.change_root_to_parent, opts("Up"))
109+
vim.keymap.set("n", "?", api.tree.toggle_help, opts("Help"))
110+
end
106111

107-
-- pass to setup along with your other options
108-
require("nvim-tree").setup {
109-
---
110-
on_attach = my_on_attach,
111-
---
112-
}
112+
-- pass to setup along with your other config
113+
require("nvim-tree").setup({
114+
---
115+
on_attach = my_on_attach,
116+
---
117+
})
113118
```
114119

115-
### Highlight
120+
### Highlight Groups
121+
122+
See [:help nvim-tree-highlight-groups](doc/nvim-tree-lua.txt)
116123

117124
Run `:NvimTreeHiTest` to show all the highlights that nvim-tree uses.
118125

119126
They can be customised before or after setup is called and will be immediately
120127
applied at runtime. e.g.
121128

122129
```lua
123-
vim.cmd([[
124-
:hi NvimTreeExecFile guifg=#ffa0a0
125-
:hi NvimTreeSpecialFile guifg=#ff80ff gui=underline
126-
:hi NvimTreeSymlink guifg=Yellow gui=italic
127-
:hi link NvimTreeImageFile Title
128-
]])
130+
vim.cmd([[
131+
:hi NvimTreeExecFile guifg=#ffa0a0
132+
:hi NvimTreeSpecialFile guifg=#ff80ff gui=underline
133+
:hi NvimTreeSymlink guifg=Yellow gui=italic
134+
:hi link NvimTreeImageFile Title
135+
]])
129136
```
130-
See [:help nvim-tree-highlight](doc/nvim-tree-lua.txt) for details.
131137

132138
## Commands
133139

134140
See [:help nvim-tree-commands](doc/nvim-tree-lua.txt)
135141

136-
Basic commands:
142+
Some commands may be executed with a bang `!` or take a `path` string argument.
143+
144+
All commands execute public API.
137145

138-
`:NvimTreeToggle` Open or close the tree. Takes an optional path argument.
146+
Some basic commands:
139147

140-
`:NvimTreeFocus` Open the tree if it is closed, and then focus on the tree.
148+
`:NvimTreeFocus` [:help nvim_tree.api.tree.open()](doc/nvim-tree-lua.txt)
149+
```lua
150+
require("nvim-tree.api").tree.open()
151+
```
152+
153+
`:NvimTreeToggle` [:help nvim_tree.api.tree.toggle()](doc/nvim-tree-lua.txt)
154+
```lua
155+
require("nvim-tree.api").tree.toggle({
156+
path = "<args>",
157+
find_file = false,
158+
update_root = false,
159+
focus = true,
160+
})
161+
```
141162

142-
`:NvimTreeFindFile` Move the cursor in the tree for the current buffer, opening folders if needed.
163+
`:NvimTreeFindFile` [:help nvim_tree.api.tree.find_file()](doc/nvim-tree-lua.txt)
164+
```lua
165+
require("nvim-tree.api").tree.find_file({
166+
open = true,
167+
update_root = "<bang>",
168+
focus = true,
169+
})
170+
```
171+
172+
`:NvimTreeCollapse` [:help nvim_tree.api.tree.collapse_all()](doc/nvim-tree-lua.txt)
143173

144-
`:NvimTreeCollapse` Collapses the nvim-tree recursively.
174+
```lua
175+
require("nvim-tree.api").tree.collapse_all({
176+
keep_buffers = false
177+
})
178+
```
145179

146180
## Roadmap
147181

@@ -155,6 +189,7 @@ Development is focused on:
155189
* Quality of Life improvements
156190
* API / Events
157191
* Enhancements to existing features
192+
- Multi-instance capabilities
158193

159194
## API
160195

‎doc/nvim-tree-lua.txt‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ via |nvim_tree.config| {on_attach} e.g. >lua
187187
vim.keymap.set("n", "?", api.tree.toggle_help, opts("Help"))
188188
end
189189

190-
-- pass to setup along with your other options
190+
-- pass to setup along with your other config
191191
require("nvim-tree").setup({
192192
---
193193
on_attach = my_on_attach,
@@ -202,19 +202,19 @@ Run |:NvimTreeHiTest| to show all the highlights that nvim-tree uses.
202202
They can be customised before or after setup is called and will be immediately
203203
applied at runtime. e.g. >lua
204204

205-
vim.cmd([[
206-
:hi NvimTreeExecFile guifg=#ffa0a0
207-
:hi NvimTreeSpecialFile guifg=#ff80ff gui=underline
208-
:hi NvimTreeSymlink guifg=Yellow gui=italic
209-
:hi link NvimTreeImageFile Title
210-
]])
205+
vim.cmd([[
206+
:hi NvimTreeExecFile guifg=#ffa0a0
207+
:hi NvimTreeSpecialFile guifg=#ff80ff gui=underline
208+
:hi NvimTreeSymlink guifg=Yellow gui=italic
209+
:hi link NvimTreeImageFile Title
210+
]])
211211
<
212212
See |nvim-tree-highlight-groups| for details.
213213

214214
==============================================================================
215215
Commands *nvim-tree-commands*
216216

217-
Commands may be executed with a `<bang>` (`!`) or take a `path` string argument.
217+
Some commands may be executed with a |<bang>| `!` or take a `path` string argument.
218218

219219
All commands execute public API.
220220

@@ -1596,8 +1596,8 @@ Config: system_open *nvim-tree-config-system-open*
15961596
• macOS: `open`
15971597
• Windows: `cmd`
15981598

1599-
Once nvim-tree minimum Nvim version is updated to 0.10, these options will
1600-
no longer be necessary and will be removed.
1599+
Once nvim-tree minimum Nvim version is updated to 0.10, this configuration
1600+
will no longer be necessary and will be removed.
16011601

16021602
Fields: ~
16031603
• {cmd}? (`string`) The open command itself
@@ -2059,7 +2059,7 @@ Config: log *nvim-tree-config-log*
20592059
• {all}? (`boolean`, default: `false`) Everything.
20602060
• {profile}? (`boolean`, default: `false`) Timing of some
20612061
operations.
2062-
• {config}? (`boolean`, default: `false`) Options and mappings, at
2062+
• {config}? (`boolean`, default: `false`) Config and mappings, at
20632063
startup.
20642064
• {copy_paste}? (`boolean`, default: `false`) File copy and paste
20652065
actions.

‎lua/nvim-tree/_meta/classes.lua‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
error("Cannot require a meta file")
33

44

5+
-- TODO #2688
56
-- These node subclasses are not ready for public exposure as they are:
67
-- - not classic classes
78
-- - only used in a few locations: api.tree.get_nodes and UserDecorator

‎lua/nvim-tree/_meta/config/log.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ error("Cannot require a meta file")
2828
---(default: `false`)
2929
---@field profile? boolean
3030
---
31-
---Options and mappings, at startup.
31+
---Config and mappings, at startup.
3232
---(default: `false`)
3333
---@field config? boolean
3434
---

‎lua/nvim-tree/_meta/config/system_open.lua‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ error("Cannot require a meta file")
1212
--- - macOS: `open`
1313
--- - Windows: `cmd`
1414
---
15-
---Once nvim-tree minimum Nvim version is updated to 0.10, these options will no longer be necessary and will be removed.
15+
---Once nvim-tree minimum Nvim version is updated to 0.10, this configuration will no longer be necessary and will be removed.
1616
---
1717
---@class nvim_tree.config.system_open
1818
---

0 commit comments

Comments
 (0)