mini.nvim/doc/mini-icons.txt at main · scottmckendry/mini.nvim

Repository navigation

History

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

*mini.icons* Icon provider

*MiniIcons*

==============================================================================

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()|.

# 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 va 10BC8 lues.

# 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.

- 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()*

`MiniIcons.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` be '󰢱' and `hl` be 'MiniIconsAzure'

local icon, hl = 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.

- 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()|.

- 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.

Supported icon names: any supported category name.

Examples: >lua

MiniIcons.get('default', 'file')

- `'directory'` - icon data for directory path.

Supported icon names: any string, but only basename will be used.

Can be used for not existing paths (no check is done).

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.

Supported icon names: any string (without extra dot prefix).

Icon data is attempted to be resolved in the following order:

- List of manually tracked extensions (for better performance).

- Filetype as a result of |vim.filetype.match()| with placeholder

file basename. 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.

Supported icon names: any string, but only basename will be used.

Can be used for not existing paths (no check is done).

Icon data is attempted to be resolved in the following order:

- List of manually tracked file basenames (should match exactly).

- List of manually tracked 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.

Supported icon names: any string.

Examples: >lua

MiniIcons.get('filetype', 'lua')

MiniIcons.get('filetype', 'help')

MiniIcons.get('filetype', 'minifiles')

- `'lsp'` - icon data for various "LSP kind" values.

Supported icon names: any string.

Examples: >lua

MiniIcons.get('lsp', 'array')

MiniIcons.get('lsp', 'keyword')

- `'os'` - icon data for popular operating systems.

Supported icon names: any string.

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])` Tuple of icon string and a highlight group name it is

suggested to be highlighted with. Example: >lua

-- Results into `icon` be '󰢱' and `hl` be 'MiniIconsAzure'

local icon, hl = MiniIcons.get('file', 'file.lua')

------------------------------------------------------------------------------

*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 until all relevant to you plugins 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:

FilesExpand file tree

mini-icons.txt

Latest commit

History

mini-icons.txt

File metadata and controls