Something went wrong. Try again.
Library of 45+ independent Lua modules improving Neovim experience with minimal effort nvim-mini.org/mini.nvim
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434*mini.notify* Show notifications
MIT License Copyright (c) 2024 Evgeni Chasnovski
------------------------------------------------------------------------------ *MiniNotify*Features:
- Show one or more highlighted notifications in a single floating window.
- Manage notifications (add, update, remove, clear).
- Custom |vim.notify()| implementation. To adjust, use |MiniNotify.make_notify()| or save-restore `vim.notify` manually after calling |MiniNotify.setup()|.
- Automated show of LSP progress report.
- Track history which can be accessed with |MiniNotify.get_all()| and shown with |MiniNotify.show_history()|.
# Setup ~
This module needs a setup with `require('mini.notify').setup({})` (replace`{}` with your `config` table). It will create global Lua table `MiniNotify`which you can use for scripting or manually (with `:lua MiniNotify.*`).
See |MiniNotify.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside`vim.b.mininotify_config` which should have same structure as`MiniNotify.config`. See |mini.nvim-buffer-local-config| for more details.
# Comparisons ~
- [j-hui/fidget.nvim](https://github.com/j-hui/fidget.nvim): - Basic goals of providing interface for notifications are similar. - Has more configuration options and visual effects, while this module does not (by design).
- [rcarriga/nvim-notify](https://github.com/rcarriga/nvim-notify): - Similar to `j-hui/fidget.nvim`.
# Highlight groups ~*MiniNotify-hl-groups*
- `MiniNotifyBorder` - window border.- `MiniNotifyLspProgress` - notifications from built-in LSP progress report.- `MiniNotifyNormal` - basic foreground/background highlighting.- `MiniNotifyTitle` - window title.
To change any highlight group, set it directly with |nvim_set_hl()|.
NOTE: |vim.notify()| override after |MiniNotify.make_notify()| uses ownhighlight groups per notification level.
# Disabling ~
To disable showing notifications, set `vim.g.mininotify_disable` (globally) or`vim.b.mininotify_disable` (for a buffer) to `true`. Considering high numberof different scenarios and customization intentions, writing exact rulesfor disabling module's functionality is left to user. See|mini.nvim-disabling-recipes| for common recipes.
------------------------------------------------------------------------------ *MiniNotify-specification*# Notification specification ~
Notification is a table with the following keys:
- <msg> `(string)` - single string with notification message. Use `\n` to delimit several lines.- <level> `(string)` - notification level as key of |vim.log.levels|. Like "ERROR", "WARN", "INFO", etc.- <hl_group> `(string)` - highlight group with which notification is shown.- <data> `(table)` - extra data to store in notification (like `source`, etc.).- <ts_add> `(number)` - timestamp of when notification is added.- <ts_update> `(number)` - timestamp of the latest notification update.- <ts_remove> `(number|nil)` - timestamp of when notification is removed. It is `nil` if notification was never removed and thus considered "active".
Notes:- Timestamps are compatible with |strftime()| and have fractional part.
------------------------------------------------------------------------------ *MiniNotify.setup()* `MiniNotify.setup`({config})Module setup
This will also:- Set |vim.notify()| custom implementation (see |MiniNotify.make_notify()|).- Clean the history. Use `MiniNotify.setup(MiniNotify.config)` to force clean history while preserving the config.
Parameters ~{config} `(table|nil)` Module config table. See |MiniNotify.config|.
Usage ~>lua require('mini.notify').setup() -- use default config -- OR require('mini.notify').setup({}) -- replace {} with your config table<------------------------------------------------------------------------------ *MiniNotify.config* `MiniNotify.config`Defaults ~>lua MiniNotify.config = { -- Content management content = { -- Function which formats the notification message -- By default prepends message with notification time format = nil,
-- Function which orders notification array from most to least important -- By default orders first by level and then by update timestamp sort = nil, },
-- Notifications about LSP progress lsp_progress = { -- Whether to enable showing enable = true,
-- Notification level level = 'INFO',
-- Duration (in ms) of how long last message should be shown duration_last = 1000, },
-- Window options window = { -- Floating window config config = {},
-- Maximum window width as share (between 0 and 1) of available columns max_width_share = 0.382,
-- Value of 'winblend' option winblend = 25, }, }<# Content ~
`config.content` defines how notifications are shown.
`content.format` is a function which takes single notification object(see |MiniNotify-specification|) and returns a string to be used directlywhen showing notification.Default: `nil` for |MiniNotify.default_format()|.
`content.sort` is a function which takes array of notification objects(see |MiniNotify-specification|) and returns an array of such objects.It can be used to define custom order and/or filter for notifications whichare shown simultaneously.Note: Input contains notifications before applying `content.format`.Default: `nil` for |MiniNotify.default_sort()|.
Example: >lua
require('mini.notify').setup({ content = { -- Use notification message as is for LSP progress format = function(notif) if notif.data.source == 'lsp_progress' then return notif.msg end return MiniNotify.default_format(notif) end,
-- Show more recent notifications first sort = function(notif_arr) table.sort( notif_arr, function(a, b) return a.ts_update > b.ts_update end ) return notif_arr end, }, })<# LSP progress ~
`config.lsp_progress` defines automated notifications for LSP progress.It is implemented as a single updating notification per progress with allinformation about it.Setting up is done inside |MiniNotify.setup()| via scheduled (|vim.schedule()|)setting of |lsp-handler| for "$/progress" method.
`lsp_progress.enable` is a boolean indicating whether LSP progress shouldbe shown in notifications. Can be disabled in current session.Default: `true`. Note: Should be `true` during |MiniNotify.setup()| call to be ableto enable it in current session.
`lsp_progress.level` is a level to be used in |MiniNotify.add()|.Default: `'INFO'`.
`lsp_progress.duration_last` is a number of milliseconds for the last progressreport to be shown on screen before removing it.Default: 1000.
Notes:- This respects previously set handler by saving and calling it.- Overriding "$/progress" method of `vim.lsp.handlers` disables notifications.- All LSP progress notifications set the following fields in `data`: - <source> is `"lsp_progress"`. - <client_name> is set to client's name (provided by client or inferred). - <context> is the latest LSP request context (`ctx` arg of |lsp-handler|). - <response> is the latest LSP response (`result` arg of |lsp-handler|).
# Window ~
`config.window` defines behavior of notification window.
`window.config` is a table defining floating window characteristicsor a callable returning such table (will be called with identifier ofwindow's buffer already showing notifications). It should have the samestructure as in |nvim_open_win()|. It has the following default valueswhich show notifications in the upper right corner with upper limit on width:- `width` is chosen to fit buffer content but at most `window.max_width_share` share of |'columns'|. To have higher maximum width, use function in `config.window` which computes dimensions inside of it (based on buffer content).- `height` is chosen to fit buffer content with enabled |'wrap'| (assuming default value of `width`).- `anchor`, `col`, and `row` are "NE", |'columns'|, and 0 or 1 (depending on tabline).- `border` is "single".- `zindex` is 999 to be as much on top as reasonably possible.
`window.max_width_share` defines maximum window width as a share of |'columns'|.Should be a number between 0 (not included) and 1.Default: 0.382.
Example for showing notifications in bottom right corner: >lua
local win_config = function() local has_statusline = vim.o.laststatus > 0 local pad = vim.o.cmdheight + (has_statusline and 1 or 0) return { anchor = 'SE', col = vim.o.columns, row = vim.o.lines - pad } end require('mini.notify').setup({ window = { config = win_config } })<`window.winblend` defines |'winblend'| value for notification window.Default: 25.
------------------------------------------------------------------------------ *MiniNotify.make_notify()* `MiniNotify.make_notify`({opts})Make vim.notify wrapper
Calling this function creates an implementation of |vim.notify()| powered bythis module. General idea is to show notification as soon as safely possible(see |vim.schedule_wrap()|) and remove it after a configurable amount of time.
All notifications set `source = "vim.notify"` in their `data` field.
This is used with default options inside |MiniNotify.setup()|. To adjust,call manually after `setup()`. For example, to show errors longer: >lua
require('mini.notify').setup() vim.notify = MiniNotify.make_notify({ ERROR = { duration = 10000 } })<To preserve original `vim.notify`: >lua
local notify_orig = vim.notify require('mini.notify').setup() vim.notify = notify_orig<Parameters ~{opts} `(table|nil)` Options to configure behavior of notification `level` (as in |MiniNotify.add()|). Fields are the same as names of `vim.log.levels` with values being tables with possible fields: - <duration> `(number)` - duration (in ms) of how much a notification should be shown. If 0 or negative, notification is not shown at all. - <hl_group> `(string)` - highlight group of notification. Only data different to default can be supplied.
Default: >lua
{ ERROR = { duration = 5000, hl_group = 'DiagnosticError' }, WARN = { duration = 5000, hl_group = 'DiagnosticWarn' }, INFO = { duration = 5000, hl_group = 'DiagnosticInfo' }, DEBUG = { duration = 0, hl_group = 'DiagnosticHint' }, TRACE = { duration = 0, hl_group = 'DiagnosticOk' }, OFF = { duration = 0, hl_group = 'MiniNotifyNormal' }, }<------------------------------------------------------------------------------ *MiniNotify.add()* `MiniNotify.add`({msg}, {level}, {hl_group}, {data})Add notification
Add notification to history. It is considered "active" and is shown.To hide, call |MiniNotify.remove()| with identifier this function returns.
Example: >lua
local id = MiniNotify.add('Hello', 'WARN', 'Comment') vim.defer_fn(function() MiniNotify.remove(id) end, 1000)<Parameters ~{msg} `(string)` Notification message.{level} `(string|nil)` Notification level as key of |vim.log.levels|. Default: `'INFO'`.{hl_group} `(string|nil)` Notification highlight group. Default: `'MiniNotifyNormal'`.{data} `(table|nil)` Extra data to store in the notification. Default: `{}`.
Return ~`(number)` Notification identifier.
------------------------------------------------------------------------------ *MiniNotify.update()* `MiniNotify.update`({id}, {new})Update active notification
Modify contents of active notification.
Parameters ~{id} `(number)` Identifier of currently active notification as returned by |MiniNotify.add()|.{new} `(table)` Table with contents to update. Keys should be as non-timestamp fields of |MiniNotify-specification| and values - new content values. If present, field `data` is updated as is. Use |MiniNotify.get()| together with |vim.tbl_deep_extend()| to change only part of it.
------------------------------------------------------------------------------ *MiniNotify.remove()* `MiniNotify.remove`({id})Remove notification
If notification is active, make it not active (by setting `ts_remove` field).If not active, do nothing.
Parameters ~{id} `(number|nil)` Identifier of previously added notification. If it is not, nothing is done (silently).
------------------------------------------------------------------------------ *MiniNotify.clear()* `MiniNotify.clear`()Remove all active notifications
Hide all active notifications and stop showing window (if shown).
------------------------------------------------------------------------------ *MiniNotify.refresh()* `MiniNotify.refresh`()Refresh notification window
Make notification window show relevant information:- Create an array of active notifications (see |MiniNotify-specification|).- Apply `config.content.sort` to an array. If output has zero notifications, make notification window to not show.- Apply `config.content.format` to each element of notification array and update its message.- Construct content from notifications and show them in a window.
Note: effects are delayed if inside fast event (|vim.in_fast_event()|).
------------------------------------------------------------------------------ *MiniNotify.get()* `MiniNotify.get`({id})Get previously added notification by id
Parameters ~{id} `(number)` Identifier of notification.
Return ~`(table)` Notification object (see |MiniNotify-specification|).
------------------------------------------------------------------------------ *MiniNotify.get_all()* `MiniNotify.get_all`()Get all previously added notifications
Get map of used notifications with keys being notification identifiers.
Can be used to get only active notification objects. Example: >lua
-- Get active notifications vim.tbl_filter( function(notif) return notif.ts_remove == nil end, MiniNotify.get_all() )<Return ~`(table)` Map with notification object values (see |MiniNotify-specification|). Note: messages are taken from last valid update.
------------------------------------------------------------------------------ *MiniNotify.show_history()* `MiniNotify.show_history`()Show history
Open or reuse a scratch buffer with all previously shown notifications.
Notes:- Content is ordered from oldest to newest based on latest update time.- Message is formatted with `config.content.format`.
------------------------------------------------------------------------------ *MiniNotify.default_format()* `MiniNotify.default_format`({notif})Default content format
Used by default as `config.content.format`. Prepends notification messagewith the human readable update time and a separator.
Parameters ~{notif} `(table)` Notification object (see |MiniNotify-specification|).
Return ~`(string)` Formatted notification message.
------------------------------------------------------------------------------ *MiniNotify.default_sort()* `MiniNotify.default_sort`({notif_arr})Default content sort
Used by default as `config.content.sort`. First sorts by notification's `level`("ERROR" > "WARN" > "INFO" > "DEBUG" > "TRACE" > "OFF"; the bigger the moreimportant); if draw - by latest update time (the later the more important).
Parameters ~{notif_arr} `(table)` Array of notifications (see |MiniNotify-specification|).
Return ~`(table)` Sorted array of notifications.
vim:tw=78:ts=8:noet:ft=help:norl: