Repository navigation
Expand file tree
/
Copy pathmini-icons.txt
More file actions
424 lines (334 loc) · 16.4 KB
/
Copy pathmini-icons.txt
File metadata and controls
424 lines (334 loc) · 16.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
*mini.icons* Icon provider
*MiniIcons*
MIT License Copyright (c) 2024 Evgeni Chasnovski
==============================================================================
Features:
- Provide icons with their highlighting via a single |MiniIcons.get()| for
various categories: filetype, file/directory path, extension, operating
system, LSP kind values. Icons and category defaults can be overridden.
- Configurable styles: "glyph" (icon glyphs) or "ascii" (non-glyph fallback).
- Fixed set of highlight groups (linked to built-in groups by default) for
better blend with color scheme.
- Caching for maximum performance.
- Integration with |vim.filetype.add()| and |vim.filetype.match()|.
- Mocking methods of 'nvim-tree/nvim-web-devicons' for better integrations
with plugins outside 'mini.nvim'. See |MiniIcons.mock_nvim_web_devicons()|.
Notes:
<
8000
div>
- It is not a goal to become a collection of icons for as much use cases as
possible. There are specific criteria for icon data to be included as
built-in in each category (see |MiniIcons.get()|).
The main supported category is "filetype".
# Dependencies ~
Suggested dependencies:
- Terminal emulator that supports showing special utf8 glyphs, possibly with
"overflow" view (displaying is done not in one but two visual cells).
Most modern feature-rich terminal emulators support this out of the box:
WezTerm, Kitty, Alacritty, iTerm2, Ghostty.
Not having "overflow" feature only results into smaller icons.
Not having support for special utf8 glyphs will result into seemingly
random symbols (or question mark squares) instead of icon glyphs.
- Font that supports Nerd Fonts (https://www.nerdfonts.com) icons from
version 3.0.0+ (in particular `nf-md-*` class).
This should be configured on terminal emulator level either by using font
patched with Nerd Fonts icons or using `NerdFontsSymbolsOnly` font as
a fallback for glyphs that are not supported in main font.
If using terminal emulator and/or font with icon support is impossible, use
`config.style = 'ascii'`. It will use a (less visually appealing) set of
non-glyph icons.
# Setup ~
This module needs a setup with `require('mini.icons').setup({})` (replace `{}`
with your `config` table). It will create global Lua table `MiniIcons` which you
can use for scripting or manually (with `:lua MiniIcons.*`).
See |MiniIcons.config| for `config` structure and default values.
# Comparisons ~
- 'nvim-tree/nvim-web-devicons' (for users):
- Sets individual colors to each icon with separate specific highlight
groups, while this modules uses fixed set of highlight groups.
This makes it easier to customize in bulk and actually blend with any
color scheme.
- This module prefers richer set of `nf-md-*` (from "Material design" set)
Nerd Fonts icons while 'nvim-web-devicons' mostly prefers `nf-dev-*`
(from "devicons" set).
- Supported categories are slightly different (with much overlap).
- Both support customization of any icon. Only this module supports
customization of default ones per supported category.
- Using this module can occasionally result in small delays when used
synchronously for many times to get icons for not typical files (like
in |mini.files|). This is due to using |vim.filetype.match()| fallback and
is present only during first call, as value is cached for later uses.
- This module supports different icon styles (like "ascii" for when using
glyphs is not possible), while 'nvim-web-devicons' does not.
- This module provides |MiniIcons.mock_nvim_web_devicons()| function which
when called imitates installed 'nvim-web-devicons' plugin to support
other plugins which do not provide 'mini.icons' yet.
- 'nvim-tree/nvim-web-devicons' (for plugin developers):
- Both have main "get icon" type of function:
- Both return tuple of icon and highlight group strings.
- This module always returns icon data possibly falling back to
user's configured default, while 'nvim-web-devicons' is able to
return `nil`. This module's approach is more aligned with the most
common use case of always showing an icon instead or near some data.
There is a third returned value indicating if output is a result of
a fallback (see |MiniIcons.get()|).
- This module uses |vim.filetype.match()| as a fallback for "file"
and "extension" categories, while 'nvim-web-devicons' completely
relies on the manually maintained tables of supported filenames
and extensions.
Using fallback results in a wider support and deeper integration
with Neovim's filetype detection at the cost of occasional slower
first call. The difference is reduced as much as is reasonable by
also having some manually tracked data tables for common cases.
- This module caches all its return values resulting in really fast
next same argument calls, while 'nvim-web-devicons' doesn't do that.
- This module works with full file/directory paths as input.
- Different sets of supported categories (see |MiniIcons.config|):
- Both support "file", "extension", "filetype", "operating system".
Albeit in different volumes: 'nvim-web-devicons' covers more
cases for "operating system", while this module has better eventual
coverage for other cases.
- This module supports "directory" and "lsp" categories.
- 'nvim-web-devicons' covers "desktop environment" and "window
management" categories. This modules does not include them due to
relatively low demand.
# Highlight groups ~
Only the following set of highlight groups is used as icon highlight.
It is recommended that they all only define colored foreground:
* `MiniIconsAzure` - azure.
* `MiniIconsBlue` - blue.
* `MiniIconsCyan` - cyan.
* `MiniIconsGreen` - green.
* `MiniIconsGrey` - grey.
* `MiniIconsOrange` - orange.
* `MiniIconsPurple` - purple.
* `MiniIconsRed` - red.
* `MiniIconsYellow` - yellow.
To change any highlight group, modify it directly with |:highlight|.
------------------------------------------------------------------------------
*MiniIcons.setup()*
`MiniIco
8000
ns.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniIcons.config|.
Usage ~
>lua
require('mini.icons').setup() -- use default config
-- OR
require('mini.icons').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniIcons.config*
`MiniIcons.config`
Module config
Default values:
>lua
MiniIcons.config = {
-- Icon style: 'glyph' or 'ascii'
style = 'glyph',
-- Customize per category. See `:h MiniIcons.config` for details.
default = {},
directory = {},
extension = {},
file = {},
filetype = {},
lsp = {},
os = {},
}
<
# Style ~
`config.style` is a string defining which icon style to use. It can be:
- `'glyph'` (default) - use glyph icons (like and ).
- `'ascii'` - use fallback ASCII-compatible icons. Those are computed as
an upper first character of the icon's resolved name inside its category.
Examples: >lua
MiniIcons.get('file', 'Makefile') -- Has `'M'` as icon
MiniIcons.get('extension', 'lua') -- Has `'L'` as icon
MiniIcons.get('file', 'file.lua') -- Has `'L'` as icon; it is resolved to
-- come from 'lua' 'extension' category
MiniIcons.get('file', 'myfile') -- Has `'F'` as icon; it is resolved to
-- come from 'file' 'default' category
<
# Customization per category ~
The following entries can be used to customize icons for supported categories:
- `config.default`
- `config.directory`
- `config.extension`
- `config.file`
- `config.filetype`
- `config.lsp`
- `config.os`
Customization should be done by supplying a table with <glyph> (icon glyph)
and/or <hl> (name of highlight group) string fields as a value for an icon
name entry. Example: >lua
require('mini.icons').setup({
default = {
-- Override default glyph for "file" category (reuse highlight group)
file = { glyph = '' },
},
extension = {
-- Override highlight group (not necessary from 'mini.icons')
lua = { hl = 'Special' },
-- Add icons for custom extension. This will also be used in
-- 'file' category for input like 'file.my.ext'.
['my.ext'] = { glyph = '', hl = 'MiniIconsRed' },
},
})
<
Notes:
- These customizations only take effect inside |MiniIcons.setup()| call.
Changing interactively via `:lua MiniIcons.config.xxx = { ... }` does not work
for performance reasons.
- Use lower case names for categories which are matched ignoring case.
See |MiniIcons.get()| for more details.
------------------------------------------------------------------------------
*MiniIcons.get()*
`MiniIcons.get`({category}, {name})
Get icon data
Usage example: >lua
-- Results into `icon=''`, `hl='MiniIconsAzure'`, `is_default=false`
local icon, hl, is_default = MiniIcons.get('file', 'file.lua')
<
Notes:
- Always returns some data, even if icon name is not explicitly supported
within target category. Category "default" is used as a fallback. Use third
output value to check if this particular case is a result of a fallback.
- Glyphs are explicitly preferred (when reasonable) from a richer set of
`nf-md-*` class ("Material design" set) of Nerd Fonts icons.
- Output is cached after the first call to increase performance of next calls
with same arguments. To reset cache, call |MiniIcons.setup()|.
- To increase first call performance for "extension" and "file" categories,
add frequently used values in |MiniIcons.config|. They will be preferred
over executing |vim.filetype.match()|.
- Matching icon name for "file" and "directory" categories is done exactly
and respecting case. Others are done ignoring case.
- The recommended way to use this function in plugin is first checking if
`_G.MiniIcons` table is present (which means that user explicitly enabled
'mini.icons') and provide icons only if it is.
Parameters ~
{category} `(string)` Category name. Supported categories:
- `'default'` - icon data used as fallback for any category.
Icon names:
- <Input>: any supported category name.
- <Built-in>: only supported category names.
Examples: >lua
MiniIcons.get('default', 'file')
<
- `'directory'` - icon data for directory path.
Icon names:
- <Input>: any string, but only basename is used. Works with not present
paths (no check is done).
- <Built-in>: popular directory names not tied to language/software
(with few notable exceptions like Neovim, Git, etc.).
Examples: >lua
-- All of these will result in the same output
MiniIcons.get('directory', '.config')
MiniIcons.get('directory', '~/.config')
MiniIcons.get('directory', '/home/user/.config')
-- Results in different output
MiniIcons.get('directory', '.Config')
<
- `'extension'` - icon data for extension.
Icon names:
- <Input>: any string (without extra dot prefix).
- <Built-in>: popular extensions not tied to language/software (with
few notable exceptions) and without associated filetype; plus a set
of filetype associated extensions (for performance or better support).
Icon data is attempted to be resolved in the following order:
- List of built-in and user configured extensions (for better
performance). Run `:=MiniIcons.list('extension')` to see them.
- Filetype as a result of |vim.filetype.match()| with placeholder
file name. Uses output of corresponding "filetype" category.
Examples: >lua
-- All of these will result in the same output
MiniIcons.get('extension', 'lua')
MiniIcons.get('extension', 'LUA')
<
- `'file'` - icon data for file path.
Icon names:
- <Input>: any string, but only basename is used. Works with not present
paths (no check is done).
- <Built-in>: popular file names not tied to language/software
(with few notable exceptions like Neovim, Git, etc.).
Icon data is attempted to be resolved in the following order:
- List of built-in and user configured file names (to match exactly).
Run `:=MiniIcons.list('flle')` to see them.
- List of built-in and user configured extensions.
Run `:=MiniIcons.list('extension')` to see them.
This step also includes already cached extensions.
Uses output of corresponding "extension" category.
- Filetype as a result of |vim.filetype.match()|.
Uses output of corresponding "filetype" category.
Examples: >lua
-- All of these will result in the same output
MiniIcons.get('file', 'init.lua')
MiniIcons.get('file', '~/.config/nvim/init.lua')
MiniIcons.get('file', '/home/user/.config/nvim/init.lua')
-- Results in different output
MiniIcons.get('file', 'Init.lua')
MiniIcons.get('file', 'init.LUA')
<
- `'filetype'` - icon data for 'filetype' values.
Icon names:
- <Input>: any string.
- <Built-in>: any filetype that is reasonably used in Neovim ecosystem.
This category is intended as a widest net for supporting use cases.
Users are encouraged to have a specific filetype detection set up.
Examples: >lua
MiniIcons.get('filetype', 'lua')
MiniIcons.get('filetype', 'help')
MiniIcons.get('filetype', 'minifiles')
<
- `'lsp'` - icon data for various "LSP kind" values.
Icon names:
- <Input>: any string.
- <Built-in>: only namesspace entries from LSP specification that are
can be displayed to user. Like `CompletionItemKind`, `SymbolKind`, etc.
Examples: >lua
MiniIcons.get('lsp', 'array')
MiniIcons.get('lsp', 'keyword')
<
- `'os'` - icon data for popular operating systems.
Icon names:
- <Input>: any string.
- <Built-in>: only operating systems which have `nf-md-*` class icon.
Examples: >lua
MiniIcons.get('os', 'linux')
MiniIcons.get('os', 'arch')
MiniIcons.get('os', 'macos')
<
{name} `(string)` Icon name within category. Use |MiniIcons.list()| to get icon
names which are explicitly supported for specific category.
Return ~
`([string,string,boolean])` Tuple of icon string, highlight group name it is
suggested to be highlighted with, and boolean indicating whether this icon
was returned as a result of fallback to default. Example: >lua
-- Results into `icon=''`, `hl='MiniIconsAzure'`, `is_default=false`
local icon, hl, is_default = MiniIcons.get('file', 'file.lua')
-- Results into `icon=''`, `hl='MiniIconsGrey'`, `is_default=true`
local icon, hl, is_default = MiniIcons.get('file', 'not-supported')
<
------------------------------------------------------------------------------
*MiniIcons.list()*
`MiniIcons.list`({category})
List explicitly supported icon names
Parameters ~
{category} `(string)` Category name supported by |MiniIcons.get()|.
Return ~
`(table)` Array of icon names which are explicitly supported for category.
Note, that `'file'` and `'extension'` categories support much more icon names
via their fallback to using |vim.filetype.match()| with `'filetype'` category.
------------------------------------------------------------------------------
*MiniIcons.mock_nvim_web_devicons()*
`MiniIcons.mock_nvim_web_devicons`()
Mock 'nvim-web-devicons' module
Call this function to mock exported functions of 'nvim-tree/nvim-web-devicons'
plugin. It will mock all its functions which return icon data by
using |MiniIcons.get()| equivalent.
This function is useful if any plugins relevant to you depend solely on
'nvim-web-devicons' and have not yet added an integration with 'mini.icons'.
Full example of usage: >lua
require('mini.icons').setup()
MiniIcons.mock_nvim_web_devicons()
<
Works without installed 'nvim-web-devicons' and even with it installed (needs
to be called after 'nvim-web-devicons' is set up).
vim:tw=78:ts=8:noet:ft=help:norl: