8000 mini.nvim/doc/mini-icons.txt at main · nathanzeng/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

Repository navigation

mini-icons.txt

Latest commit

 

History

History
503 lines (398 loc) · 20.5 KB

mini-icons.txt

File metadata and controls

503 lines (398 loc) · 20.5 KB
Raw
- `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.
# Using extension during file resolution ~
`config.use_file_extension` is a function which can be used to control which
extensions will be considered as a source of icon data during "file" category
resolution (see |MiniIcons.get()| for more details).
Default: function which always returns `true` (i.e. consider all extensions).
Will be called once for the biggest suffix after dot found in the file name.
The arguments will be `ext` (found extension; lowercase) and `file` (input for
which icon is computed; as is). Should explicitly return `true` if `ext` is to
be considered (i.e. call `MiniIcons.get('extension', ext)` and use its
output if it is not default). Otherwise extension won't be even considered.
The primary use case for this setting is to ensure that some extensions are
ignored in order for resolution to reach |vim.filetype.match()| stage. This
is needed if there is a set up filetype detection for files with recognizable
extension and conflicting icons (which you want to use). Note: if problematic
filetype detection involves only known in advance file names, prefer using
`config.file` customization.
Example: >lua
-- Built-in filetype detection recognizes files like "queries/.*%.scm"
-- as "query" filetype. However, without special setup, 'mini.icons' will
-- use "scm" extension to resolve as Scheme file. Here is a setup to ignore
-- "scm" extension and completely rely on `vim.filetype.match()` fallback.
require('mini.icons').setup({
-- Check last letters explicitly to account for dots in file name
use_file_extension = function(ext) return ext:sub(-3) ~= 'scm' end
})
-- Another common choices for extensions to ignore: "yml", "json", "txt".
<
------------------------------------------------------------------------------
*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.
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).
< 8000 /div>
- <Built-in>: popular extensions without associated filetype plus a set
for which filetype detection gives not good enough result.
Icon data is attempted to be resolved in the following order:
- List of user configured and built-in extensions (for better results).
Run `:=MiniIcons.list('extension')` to see them.
Used also if present as suffix after the dot (widest one preferred).
- Filetype as a result of |vim.filetype.match()| with placeholder
file name. Uses icon data from "filetype" category.
Examples: >lua
-- All of these will result in the same output
MiniIcons.get('extension', 'lua')
MiniIcons.get('extension', 'LUA')
MiniIcons.get('extension', 'my.lua')
<
- `'file'` - icon data for file path.
Icon names:
- <Input>: any string. 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.) plus a set which
has recognizable extension but has special detectable filetype.
Icon data is attempted to be resolved in the following order:
- List of user configured and built-in file names (matched to basename
of the input exactly). Run `:=MiniIcons.list('file')` to see them.
- Basename extension:
- Matched directly as `get('extension', ext)`, where `ext` is the
widest suffix after the dot.
- Considered only if `config.use_file_extension` returned `true`.
- Only recognizable extensions (i.e. not default fallback) are used.
- Filetype as a result of |vim.filetype.match()| with full input (not
basename) as `filename`. Uses icon data from "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')
-- Respects full path input in `vim.filetype.match()`
MiniIcons.get('file', '.git/info/attributes')
<
- `'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 ~
`(...)` 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).
------------------------------------------------------------------------------
*MiniIcons.tweak_lsp_kind()*
`MiniIcons.tweak_lsp_kind`({mode})
Tweak built-in LSP kind names
Update in place appropriate maps in |vim.lsp.protocol| (`CompletionItemKind`
and `SymbolKind`) by using icon strings from "lsp" category. Only "numeric
id to kind name" part is updated (to preserve data from original map).
Updating is done in one of these modes:
- Append: add icon after text.
- Prepend: add icon before text (default).
- Replace: use icon instead of text.
Notes:
- Makes |mini.completion| show icons, as it uses built-in protocol map.
- Results in loading whole `vim.lsp` module, so might add significant amount
of time on startup. Call it lazily. For example, with |MiniDeps.later()|: >lua
require('mini.icons').setup()
MiniDeps.later(MiniIcons.tweak_lsp_kind)
<
Parameters ~
{mode} `(string|nil)` One of "prepend" (default), "append", "replace".
vim:tw=78:ts=8:noet:ft=help:norl:
0