retrovim 0.0.3

package/nvim/plugins/mini.nvim/doc/mini-snippets.txt

@@ -0,0 +1,1291 @@
+*mini.snippets* Manage and expand snippets
+
+MIT License Copyright (c) 2024 Evgeni Chasnovski
+
+------------------------------------------------------------------------------
+                                                                  *MiniSnippets*
+Snippet is a template for a frequently used text. Typical workflow is to type
+snippet's (configurable) prefix and expand it into a snippet session.
+
+The template usually contains both pre-defined text and places (called
+"tabstops") for user to interactively change/add text during snippet session.
+
+This module supports (only) snippet syntax defined in LSP specification (with
+small deviations). See |MiniSnippets-syntax-specification|.
+
+Features:
+- Manage snippet collection by adding it explicitly or with a flexible set of
+  performant built-in loaders. See |MiniSnippets.gen_loader|.
+
+- Configured snippets are efficiently resolved before every expand based on
+  current local context. This, for example, allows using different snippets
+  in different local tree-sitter languages (like in markdown code blocks).
+  See |MiniSnippets.default_prepare()|.
+
+- Match which snippet to insert based on the currently typed text.
+  Supports both exact and fuzzy matching. See |MiniSnippets.default_match()|.
+
+- Select from several matched snippets via `vim.ui.select()`.
+  See |MiniSnippets.default_select()|.
+
+- Start specialized in-process LSP server to show loaded snippets inside
+  (auto)completion engines (like |mini.completion|).
+  See |MiniSnippets.start_lsp_server()|.
+
+- Insert, jump, and edit during snippet session in a configurable manner:
+    - Configurable mappings for jumping and stopping.
+    - Jumping wraps around the tabstops for easier navigation.
+    - Easy to reason rules for when session automatically stops.
+    - Text synchronization of linked tabstops preserving relative indent.
+    - Dynamic tabstop state visualization (current/visited/unvisited, etc.)
+    - Inline visualization of empty tabstops (requires Neovim>=0.10).
+    - Works inside comments by preserving comment leader on new lines.
+    - Supports nested sessions (expand snippet while there is an active one).
+  See |MiniSnippets.default_insert()|.
+
+- Exported function to parse snippet body into easy-to-reason data structure.
+  See |MiniSnippets.parse()|.
+
+Notes:
+- It does not set up any snippet collection by default. Explicitly populate
+  `config.snippets` to have snippets to match from.
+- It does not come with a built-in snippet collection. It is expected from
+  users to add their own snippets, manually or with dedicated plugin(s).
+- It does not support variable/tabstop transformations in default snippet
+  session. This requires ECMAScript Regular Expression parser which can not
+  be implemented concisely.
+
+Sources with more details:
+- |MiniSnippets-glossary|
+- |MiniSnippets-overview|
+- |MiniSnippets-examples|
+- |MiniSnippets-in-other-plugins| (for plugin authors)
+
+# Dependencies ~
+
+This module doesn't come with snippet collection. Either create it manually
+or install a dedicated plugin. For example,
+[rafamadriz/friendly-snippets](https://github.com/rafamadriz/friendly-snippets).
+
+# Setup ~
+
+This module needs a setup with `require('mini.snippets').setup({})` (replace `{}`
+with your `config` table). It will create global Lua table `MiniSnippets` which
+you can use for scripting or manually (with `:lua MiniSnippets.*`).
+
+See |MiniSnippets.config| for `config` structure and default values.
+
+You can override runtime config settings locally to buffer inside
+`vim.b.minisnippets_config` which should have same structure as
+`MiniSnippets.config`. See |mini.nvim-buffer-local-config| for more details.
+
+# Comparisons ~
+
+- [L3MON4D3/LuaSnip](https://github.com/L3MON4D3/LuaSnip):
+    - Both contain functionality to load snippets from file system.
+      This module provides several common loader generators while `LuaSnip`
+      contains a more elaborate loading setup.
+      Also both require explicit opt-in for which snippets to load.
+    - Both support LSP snippet format. `LuaSnip` also provides own more
+      elaborate snippet format which is out of scope for this module.
+    - `LuaSnip` can autoexpand snippets, while this module always requires
+      an explicit user action to expand (by design).
+    - Both contain snippet expand functionality which differs in some aspects:
+        - `LuaSnip` has an elaborate dynamic tabstop visualization config.
+          This module provides a handful of dedicated highlight groups.
+        - This module provides configurable visualization of empty tabstops.
+        - `LuaSnip` implements nested sessions by essentially merging them
+          into one. This module treats each nested session separately (to not
+          visually overload) while storing them in stack (first in last out).
+        - `LuaSnip` uses |Select-mode| to power replacing current tabstop,
+          while this module always stays in |Insert-mode|. This enables easier
+          mapping understanding and more targeted highlighting.
+        - This module implements jumping which wraps after final tabstop
+          for more flexible navigation (enhanced with by a more flexible
+          autostopping rules), while `LuaSnip` autostops session once
+          jumping reached the final tabstop.
+
+- Built-in |vim.snippet| (on Neovim>=0.10):
+    - Does not contain functionality to load or match snippets (by design),
+      while this module does.
+    - Both contain expand functionality based on LSP snippet format.
+      Differences in how snippet sessions are handled are similar to
+      comparison with `LuaSnip`.
+
+- [rafamadriz/friendly-snippets](https://github.com/rafamadriz/friendly-snippets):
+    - A snippet collection plugin without features to manage or expand them.
+      This module is designed with `friendly-snippets` compatibility in mind.
+
+- [abeldekat/cmp-mini-snippets](https://github.com/abeldekat/cmp-mini-snippets):
+    - A source for [hrsh7th/nvim-cmp](https://github.com/hrsh7th/nvim-cmp)
+      that integrates |mini.snippets|.
+
+# Highlight groups ~
+*MiniSnippets-hl-groups*
+
+- `MiniSnippetsCurrent` - current tabstop.
+- `MiniSnippetsCurrentReplace` - current tabstop, placeholder is to be replaced.
+- `MiniSnippetsFinal` - special `$0` tabstop.
+- `MiniSnippetsUnvisited` - not yet visited tabstop(s).
+- `MiniSnippetsVisited` - visited tabstop(s).
+
+To change any highlight group, set it directly with |nvim_set_hl()|.
+
+# Disabling ~
+
+To disable core functionality, set `vim.g.minisnippets_disable` (globally) or
+`vim.b.minisnippets_disable` (for a buffer) to `true`. Considering high number
+of different scenarios and customization intentions, writing exact rules
+for disabling module's functionality is left to user. See
+|mini.nvim-disabling-recipes| for common recipes.
+
+# Using in other plugins ~
+*MiniSnippets-in-other-plugins*
+
+- Perform a `_G.MiniSnippets ~= nil` check before using any feature. This
+  ensures that user explicitly set up the module.
+
+- To insert snippet given its body (like |vim.snippet.expand()|), use: >lua
+
+     -- Use configured `insert` method with falling back to default
+     local insert = MiniSnippets.config.expand.insert
+       or MiniSnippets.default_insert
+     -- Insert at cursor
+     insert({ body = snippet })
+<
+- To get available snippets, use: >lua
+
+  -- Get snippets matched at cursor
+  MiniSnippets.expand({ insert = false })
+
+  -- Get all snippets available at cursor context
+  MiniSnippets.expand({ match = false, insert = false })
+<
+------------------------------------------------------------------------------
+                                                         *MiniSnippets-glossary*
+POSITION ~
+Table representing position in a buffer. Fields:
+- <line> `(number)` - line number (starts at 1).
+- <col> `(number)` - column number (starts at 1).
+
+REGION ~
+Table representing region in a buffer.
+Fields: <from> and <to> for inclusive start/end POSITIONs.
+
+SNIPPET ~
+Data about template to insert. Should contain fields:
+- <prefix> - string snippet identifier.
+- <body> - string snippet content with appropriate syntax.
+- <desc> - string snippet description in human readable form.
+
+Can also be used to mean snippet body if distinction is clear.
+
+SNIPPET SESSION ~
+Interactive state for user to adjust inserted snippet.
+
+MATCHED SNIPPET ~
+Snippet which contains <region> field with region that matched it.
+Usually region needs to be removed.
+
+SNIPPET NODE ~
+Unit of parsed snippet body. See |MiniSnippets.parse()|.
+
+TABSTOP ~
+Dedicated places in snippet body for users to interactively adjust.
+Specified in snippet body with `$` followed by digit(s).
+
+LINKED TABSTOPS ~
+Different nodes assigned the same tabstop. Updated in sync.
+
+REFERENCE NODE ~
+First (from left to right) node of linked tabstops. Used to determine
+synced text and cursor placement after jump.
+
+EXPAND ~
+Action to start snippet session based on currently typed text.
+Always done in current buffer at cursor. Executed steps:
+- `PREPARE` - resolve raw config snippets at context.
+- `MATCH` - match resolved snippets at cursor position.
+- `SELECT` - possibly choose among matched snippets.
+- `INSERT` - insert selected snippet and start snippet session.
+
+------------------------------------------------------------------------------
+                                                         *MiniSnippets-overview*
+Snippet is a template for a frequently used text. Typical workflow is to type
+snippet's (configurable) prefix and expand it into a snippet session: add some
+pre-defined text and allow user to interactively change/add at certain places.
+
+This overview assumes default config for mappings and expand.
+See |MiniSnippets.config| and |MiniSnippets-examples| for more details.
+
+# Snippet structure ~
+
+Snippet consists from three parts:
+- `Prefix` - identifier used to match against current text.
+- `Body` - actually inserted content with appropriate syntax.
+- `Desc` - description in human readable form.
+
+Example: `{ prefix = 'tis', body = 'This is snippet', desc = 'Snip' }`
+Typing `tis` and pressing "expand" mapping (<C-j> by default) will remove "tis",
+add "This is snippet", and place cursor at the end in Insert mode.
+
+# Syntax ~
+*MiniSnippets-syntax-specification*
+
+Inserting just text after typing smaller prefix is already powerful enough.
+For more flexibility, snippet body can be formatted in a special way to
+provide extra features. This module implements support for syntax defined
+in LSP specification (with small deviations). See this link for reference:
+https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#snippet_syntax
+
+A quick overview of basic syntax features:
+
+- Tabstops are snippet parts meant for interactive editing at their location.
+  They are denoted as `$1`, `$2`, etc.
+  Navigating between them is called "jumping" and is done in numerical order
+  of tabstop identifiers by pressing special keys: <C-l> and <C-h> to jump
+  to next and previous tabstop respectively.
+  Special tabstop `$0` is called "final tabstop": it is used to decide when
+  snippet session is automatically stopped and is visited last during jumping.
+
+  Example: `T1=$1 T2=$2 T0=$0` is expanded as `T1= T2= T0=` with three tabstops.
+
+- Tabstop can have placeholder: a text used if tabstop is not yet edited.
+  Text is preserved if no editing is done. It follows this same syntax, which
+  means it can itself contain tabstops with placeholders (i.e. be nested).
+  Tabstop with placeholder is denoted as `${1:placeholder}` (`$1` is `${1:}`).
+
+  Example: `T1=${1:text} T2=${2:<$1>}` is expanded as `T1=text T2=<text>`;
+           typing `x` at first placeholder results in `T1=x T2=<x>`;
+           jumping once and typing `y` results in `T1=x T2=y`.
+
+- There can be several tabstops with same identifier. They are linked and
+  updated in sync during text editing. Can also have different placeholders;
+  they are forced to be the same as in the first (from left to right) tabstop.
+
+  Example: `T1=${1:text} T1=$1` is expanded as `T1=text T1=text`;
+           typing `x` at first placeholder results in `T1=x T1=x`.
+
+- Tabstop can also have choices: suggestions about tabstop text. It is denoted
+  as `${1|a,b,c|}`. First choice is used as placeholder.
+
+  Example: `T1=${1|left,right|}` is expanded as `T1=left`.
+
+- Variables can be used to automatically insert text without user interaction.
+  As tabstops, each one can have a placeholder which is used if variable is
+  not defined. There is a special set of variables describing editor state.
+
+  Example: `V1=$TM_FILENAME V2=${NOTDEFINED:placeholder}` is expanded as
+           `V1=current-file-basename V2=placeholder`.
+
+What's different from LSP specification:
+- Special set of variables is wider and is taken from VSCode specification:
+  https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables
+  Exceptions are `BLOCK_COMMENT_START` and `BLOCK_COMMENT_END` as Neovim doesn't
+  provide this information.
+- Variable `TM_SELECTED_TEXT` is resolved as contents of |quote_quote| register.
+  It assumes that text is put there prior to expanding. For example, visually
+  select, press |c|, type prefix, and expand.
+  See |MiniSnippets-examples| for how to adjust this.
+- Environment variables are recognized and supported: `V1=$VIMRUNTIME` will
+  use an actual value of |$VIMRUNTIME|.
+- Variable transformations are not supported during snippet session. It would
+  require interacting with ECMAScript-like regular expressions for which there
+  is no easy way in Neovim. It may change in the future.
+  Transformations are recognized during parsing, though, with some exceptions:
+    - The `}` inside `if` of `${1:?if:else}` needs escaping (for technical reasons).
+
+There is a |MiniSnippets.parse()| function for programmatically parsing
+snippet body into a comprehensible data structure.
+
+# Expand ~
+
+Using snippets is done via what is called "expanding". It goes like this:
+- Type snippet prefix or its recognizable part.
+- Press <C-j> to expand. It will perform the following steps:
+    - Prepare available snippets in current context (buffer + local language).
+      This allows snippet setup to have general function loaders which return
+      different snippets in different contexts.
+    - Match text to the left of cursor with available prefixes. It first tries
+      to do exact match and falls back to fuzzy matching.
+    - If there are several matches, use `vim.ui.select()` to choose one.
+    - Insert single matching snippet. If snippet contains tabstops, start
+      snippet session.
+
+For more details about each step see:
+- |MiniSnippets.default_prepare()|
+- |MiniSnippets.default_match()|
+- |MiniSnippets.default_select()|
+- |MiniSnippets.default_insert()|
+
+Snippet session allows interactive editing at tabstop locations:
+
+- All tabstop locations are visualized depending on tabstop "state" (whether
+  it is current/visited/unvisited/final and whether it was already edited).
+  Empty tabstops are visualized with inline virtual text ("•"/"∎" for
+  regular/final tabstops). It is removed after session is stopped.
+
+- Start session at first tabstop. Type text to replace placeholder.
+  When finished with current tabstop, jump to next with <C-l>. Repeat.
+  If changed mind about some previous tabstop, jump back with <C-h>.
+  Jumping also wraps around the edge (first tabstop is next after final).
+
+- If tabstop has choices, use <C-n> / <C-p> to select next / previous item.
+
+- Starting another snippet session while there is an active one is allowed.
+  This creates nested sessions: suspend current, start the new one.
+  After newly created is stopped, resume the suspended one.
+
+- Stop session manually by pressing <C-c> or make it stop automatically:
+  if final tabstop is current either make a text edit or exit to Normal mode.
+  If snippet doesn't explicitly define final tabstop, it is added at the end
+  of the snippet.
+
+For more details about snippet session see |MiniSnippets-session|.
+
+To select and insert snippets via completion engine (that supports LSP
+completion; like |mini.completion| or |lsp-autocompletion|),
+call |MiniSnippets.start_lsp_server()| after |MiniSnippets.setup()|. This sets up
+an LSP server that matches and provides snippets loaded with |mini.snippets|.
+To match with completion engine, use `start_lsp_server({ match = false })`.
+
+# Management ~
+
+Out of the box |mini.snippets| doesn't load any snippets, it should be done
+explicitly inside |MiniSnippets.setup()| following |MiniSnippets.config|.
+
+The suggested approach to snippet management is to create dedicated files with
+snippet data and load them through function loaders in `config.snippets`.
+See |MiniSnippets-examples| for basic (yet capable) snippet management config.
+
+## File specification ~
+*MiniSnippets-file-specification*
+
+General idea of supported files is to have at least out of the box experience
+with common snippet collections. Namely "rafamadriz/friendly-snippets".
+The following files are supported:
+
+- Extensions:
+    - Read/decoded as JSON object (|vim.json.decode()|): `*.json`, `*.code-snippets`
+    - Executed as Lua file (|dofile()|) and uses returned value: `*.lua`
+
+- Content:
+    - Dict-like: object in JSON; returned table in Lua; no order guarantees.
+    - Array-like: array in JSON; returned array table in Lua; preserves order.
+
+Example of file content with a single snippet:
+- Lua dict-like:   `return { name = { prefix = 't', body = 'Text' } }`
+- Lua array-like:  `return { { prefix = 't', body = 'Text', desc = 'name' } }`
+- JSON dict-like:  `{ "name": { "prefix": "t", "body": "Text" } }`
+- JSON array-like: `[ { "prefix": "t", "body": "Text", "desc": "name" } ]`
+
+Notes:
+- There is no built-in support for VSCode-like "package.json" files. Define
+  structure manually in |MiniSnippets.setup()| via built-in or custom loaders.
+- There is no built-in support for `scope` field of snippet data. Snippets are
+  expected to be manually separated into smaller files and loaded on demand.
+
+For supported snippet syntax see |MiniSnippets-syntax-specification|.
+
+## General advice ~
+
+- Put files in "snippets" subdirectory of any path in |'runtimepath'| (like
+  `$XDG_CONFIG_HOME/nvim/snippets/global.json`).
+  This is compatible with |MiniSnippets.gen_loader.from_runtime()| and
+  example from |MiniSnippets-examples|.
+- Prefer `*.json` files with dict-like content if you want more cross platform
+  setup. Otherwise use `*.lua` files with array-like content.
+- To implement "dynamic snippet" that changes data (usually <body>) depending
+  on the context, use `*.lua` file with function returning snippet data.
+  It should be an element in the output table (dict or array like).
+
+# Demo ~
+
+The best way to grasp the design of snippet management and expansion is to
+try them out yourself. Here are steps for a basic demo:
+- Create `snippets/global.json` file in the config directory with the content: >json
+
+  {
+    "Basic":        { "prefix": "ba", "body": "T1=$1 T2=$2 T0=$0"         },
+    "Placeholders": { "prefix": "pl", "body": "T1=${1:aa}\nT2=${2:<$1>}"  },
+    "Choices":      { "prefix": "ch", "body": "T1=${1|a,b|} T2=${2|c,d|}" },
+    "Linked":       { "prefix": "li", "body": "T1=$1\n\tT1=$1"            },
+    "Variables":    { "prefix": "va", "body": "Runtime: $VIMRUNTIME\n"    },
+    "Complex":      {
+      "prefix": "co",
+      "body": [ "T1=${1:$RANDOM}", "T3=${3:$1_${2:$1}}", "T2=$2" ]
+    }
+  }
+<
+- Set up |mini.snippets| as recommended in |MiniSnippets-examples|.
+- Open Neovim. Type each snippet prefix and press <C-j> (even if there is
+  still active session). Explore from there.
+
+------------------------------------------------------------------------------
+                                                         *MiniSnippets-examples*
+# Basic snippet management config ~
+
+Example of snippet management setup that should cover most cases: >lua
+
+  -- Setup
+  local gen_loader = require('mini.snippets').gen_loader
+  require('mini.snippets').setup({
+    snippets = {
+      -- Load custom file with global snippets first
+      gen_loader.from_file('~/.config/nvim/snippets/global.json'),
+
+      -- Load snippets based on current language by reading files from
+      -- `snippets/` subdirectories from 'runtimepath' directories.
+      gen_loader.from_lang(),
+    },
+  })
+<
+This setup allows having single file with custom "global" snippets (will be
+present in every buffer) and snippets which will be loaded based on the local
+language (see |MiniSnippets.gen_loader.from_lang()|).
+
+Create language snippets manually (by creating and populating
+`$XDG_CONFIG_HOME/nvim/snippets/lua.json` file) or by installing dedicated
+snippet collection plugin (like `rafamadriz/friendly-snippets`).
+
+Note: all built-in loaders and |MiniSnippets.read_file()| cache their output
+by default. It means that after a file is first read, changing it won't have
+effect during current Neovim session. See |MiniSnippets.gen_loader| about how
+to reset cache if necessary.
+
+# Select from all available snippets in current context ~
+
+With |MiniSnippets.default_match()|, expand snippets (<C-j> by default) at line
+start or after whitespace. To be able to always select from all current
+context snippets, make mapping similar to the following: >lua
+
+  local rhs = function() MiniSnippets.expand({ match = false }) end
+  vim.keymap.set('i', '<C-g><C-j>', rhs, { desc = 'Expand all' })
+<
+# "Supertab"-like <Tab> / <S-Tab> mappings ~
+
+This module intentionally by default uses separate keys to expand and jump as
+it enables cleaner use of nested sessions. Here is an example of setting up
+custom <Tab> to "expand or jump" and <S-Tab> to "jump to previous": >lua
+
+  local snippets = require('mini.snippets')
+  local match_strict = function(snips)
+    -- Do not match with whitespace to cursor's left
+    return snippets.default_match(snips, { pattern_fuzzy = '%S+' })
+  end
+  snippets.setup({
+    -- ... Set up snippets ...
+    mappings = { expand = '', jump_next = '', jump_prev = '' },
+    expand   = { match = match_strict },
+  })
+  local expand_or_jump = function()
+    local can_expand = #MiniSnippets.expand({ insert = false }) > 0
+    if can_expand then vim.schedule(MiniSnippets.expand); return '' end
+    local is_active = MiniSnippets.session.get() ~= nil
+    if is_active then MiniSnippets.session.jump('next'); return '' end
+    return '\t'
+  end
+  local jump_prev = function() MiniSnippets.session.jump('prev') end
+  vim.keymap.set('i', '<Tab>', expand_or_jump, { expr = true })
+  vim.keymap.set('i', '<S-Tab>', jump_prev)
+<
+# Stop session immediately after jumping to final tabstop ~
+
+Utilize a dedicated |MiniSnippets-events|: >lua
+
+  local fin_stop = function(args)
+    if args.data.tabstop_to == '0' then MiniSnippets.session.stop() end
+  end
+  local au_opts = { pattern = 'MiniSnippetsSessionJump', callback = fin_stop }
+  vim.api.nvim_create_autocmd('User', au_opts)
+<
+# Stop all sessions on Normal mode exit ~
+
+Use |ModeChanged| and |MiniSnippets-events| events: >lua
+
+  local make_stop = function()
+    local au_opts = { pattern = '*:n', once = true }
+    au_opts.callback = function()
+      while MiniSnippets.session.get() do
+        MiniSnippets.session.stop()
+      end
+    end
+    vim.api.nvim_create_autocmd('ModeChanged', au_opts)
+  end
+  local opts = { pattern = 'MiniSnippetsSessionStart', callback = make_stop }
+  vim.api.nvim_create_autocmd('User', opts)
+<
+# Customize variable evaluation ~
+
+Create environment variables and `config.expand.insert` wrapper: >lua
+
+  -- Use evnironment variables with value is same for all snippet sessions
+  vim.loop.os_setenv('USERNAME', 'user')
+
+  -- Compute custom lookup for variables with dynamic values
+  local insert_with_lookup = function(snippet)
+    local lookup = {
+      TM_SELECTED_TEXT = table.concat(vim.fn.getreg('a', true, true), '\n'),
+    }
+    return MiniSnippets.default_insert(snippet, { lookup = lookup })
+  end
+
+  require('mini.snippets').setup({
+    -- ... Set up snippets ...
+    expand = { insert = insert_with_lookup },
+  })
+<
+# Using Neovim's built-ins to insert snippet ~
+
+Define custom `expand.insert` in |MiniSnippets.config| and mappings: >lua
+
+  require('mini.snippets').setup({
+    -- ... Set up snippets ...
+    expand = {
+      insert = function(snippet, _) vim.snippet.expand(snippet.body) end
+    }
+  })
+  -- Make jump mappings or skip to use built-in <Tab>/<S-Tab> in Neovim>=0.11
+  local jump_next = function()
+    if vim.snippet.active({direction = 1}) then return vim.snippet.jump(1) end
+  end
+  local jump_prev = function()
+    if vim.snippet.active({direction = -1}) then vim.snippet.jump(-1) end
+  end
+  vim.keymap.set({ 'i', 's' }, '<C-l>', jump_next)
+  vim.keymap.set({ 'i', 's' }, '<C-h>', jump_prev)
+<
+------------------------------------------------------------------------------
+                                                          *MiniSnippets.setup()*
+                         `MiniSnippets.setup`({config})
+Module setup
+
+Parameters ~
+{config} `(table|nil)` Module config table. See |MiniSnippets.config|.
+
+Usage ~
+>lua
+  require('mini.snippets').setup({}) -- replace {} with your config table
+                                     -- needs `snippets` field present
+<
+------------------------------------------------------------------------------
+                                                           *MiniSnippets.config*
+                             `MiniSnippets.config`
+Defaults ~
+>lua
+  MiniSnippets.config = {
+    -- Array of snippets and loaders (see |MiniSnippets.config| for details).
+    -- Nothing is defined by default. Add manually to have snippets to match.
+    snippets = {},
+
+    -- Module mappings. Use `''` (empty string) to disable one.
+    mappings = {
+      -- Expand snippet at cursor position. Created globally in Insert mode.
+      expand = '<C-j>',
+
+      -- Interact with default `expand.insert` session.
+      -- Created for the duration of active session(s)
+      jump_next = '<C-l>',
+      jump_prev = '<C-h>',
+      stop = '<C-c>',
+    },
+
+    -- Functions describing snippet expansion. If `nil`, default values
+    -- are `MiniSnippets.default_<field>()`.
+    expand = {
+      -- Resolve raw config snippets at context
+      prepare = nil,
+      -- Match resolved snippets at cursor position
+      match = nil,
+      -- Possibly choose among matched snippets
+      select = nil,
+      -- Insert selected snippet
+      insert = nil,
+    },
+  }
+<
+# Loaded snippets ~
+
+`config.snippets` is an array containing snippet data which can be: snippet
+table, function loader, or (however deeply nested) array of snippet data.
+
+Snippet is a table with the following fields:
+
+- <prefix> `(string|table|nil)` - string used to match against current text.
+   If array, all strings should be used as separate prefixes.
+- <body> `(string|table|nil)` - content of a snippet which should follow
+   the |MiniSnippets-syntax-specification|. Array is concatenated with `"\n"`.
+- <desc> `(string|table|nil)` - description of snippet. Can be used to display
+  snippets in a more human readable form. Array is concatenated with `"\n"`.
+
+Function loaders are expected to be called with single `context` table argument
+(containing any data about current context) and return same as `config.snippets`
+data structure.
+
+`config.snippets` is resolved with `config.prepare` on every expand.
+See |MiniSnippets.default_prepare()| for how it is done by default.
+
+For a practical example see |MiniSnippets-examples|.
+Here is an illustration of `config.snippets` customization capabilities: >lua
+
+  local gen_loader = require('mini.snippets').gen_loader
+  require('mini.snippets').setup({
+    snippets = {
+      -- Load custom file with global snippets first (order matters)
+      gen_loader.from_file('~/.config/nvim/snippets/global.json'),
+
+      -- Or add them here explicitly
+      { prefix='cdate', body='$CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE' },
+
+      -- Load snippets based on current language by reading files from
+      -- `snippets/` subdirectories from 'runtimepath' directories.
+      gen_loader.from_lang(),
+
+      -- Load project-local snippets with `gen_loader.from_file()`
+      -- and relative path (file doesn't have to be present)
+      gen_loader.from_file('.vscode/project.code-snippets'),
+
+      -- Custom loader for language-specific project-local snippets
+      function(context)
+        local rel_path = '.vscode/' .. context.lang .. '.code-snippets'
+        if vim.fn.filereadable(rel_path) == 0 then return end
+        return MiniSnippets.read_file(rel_path)
+      end,
+
+      -- Ensure that some prefixes are not used (as there is no `body`)
+      { prefix = { 'bad', 'prefix' } },
+    }
+  })
+<
+# Mappings ~
+
+`config.mappings` describes which mappings are automatically created.
+
+`mappings.expand` is created globally in Insert mode and is used to expand
+snippet at cursor. Use |MiniSnippets.expand()| for custom mappings.
+
+`mappings.jump_next`, `mappings.jump_prev`, and `mappings.stop` are created for
+the duration of active snippet session(s) from |MiniSnippets.default_insert()|.
+Used to jump to next/previous tabstop and stop active session respectively.
+Use |MiniSnippets.session.jump()| and |MiniSnippets.session.stop()| for custom
+Insert mode mappings.
+Note: do not use `"<C-n>"` or `"<C-p>"` for any action as they conflict with
+built-in completion: it forces them to mean "change focus to next/previous
+completion item". This matters more frequently than when there is a tabstop
+with choices due to how this module handles built-in completion during jumps.
+
+# Expand ~
+
+`config.expand` defines expand steps (see |MiniSnippets-glossary|), either after
+pressing `mappings.expand` or starting manually via |MiniSnippets.expand()|.
+
+`expand.prepare` is a function that takes `raw_snippets` in the form of
+`config.snippets` and should return a plain array of snippets (as described
+in |MiniSnippets-glossary|). Will be called on every |MiniSnippets.expand()| call.
+If returns second value, it will be used as context for warning messages.
+Default: |MiniSnippets.default_prepare()|.
+
+`expand.match` is a function that takes `expand.prepare` output and returns
+an array of matched snippets: one or several snippets user might intend to
+eventually insert. Should sort matches in output from best to worst.
+Entries can contain `region` field with current buffer region used to do
+the match; usually it needs to be removed (similar to how |ins-completion|
+and |abbreviations| work).
+Default: |MiniSnippets.default_match()|
+
+`expand.select` is a function that takes output of `expand.match` and function
+that inserts snippet (and also ensures Insert mode and removes snippet's match
+region). Should allow user to perform interactive snippet selection and
+insert the chosen one. Designed to be compatible with |vim.ui.select()|.
+Called for any non-empty `expand.match` output (even with single entry).
+Default: |MiniSnippets.default_select()|
+
+`expand.insert` is a function that takes single snippet table as input and
+inserts snippet at cursor position. This is a main entry point for adding
+text template to buffer and starting a snippet session.
+If called inside |MiniSnippets.expand()| (which is a usual interactive case),
+all it has to do is insert snippet at cursor position. Ensuring Insert mode
+and removing matched snippet region is done beforehand.
+Default: |MiniSnippets.default_insert()|
+
+Illustration of `config.expand` customization: >lua
+
+  -- Supply extra data as context
+  local my_p = function(raw_snippets)
+    local _, cont = MiniSnippets.default_prepare({})
+    cont.cursor = vim.api.nvim_win_get_cursor()
+    return MiniSnippets.default_prepare(raw_snippets, { context = cont })
+  end
+  -- Perform fuzzy match based only on alphanumeric characters
+  local my_m = function(snippets)
+    return MiniSnippets.default_match(snippets, { pattern_fuzzy = '%w*' })
+  end
+  -- Always insert the best matched snippet
+  local my_s = function(snippets, insert) return insert(snippets[1]) end
+  -- Use different string to show empty tabstop as inline virtual text
+  local my_i = function(snippet)
+    return MiniSnippets.default_insert(snippet, { empty_tabstop = '$' })
+  end
+
+  require('mini.snippets').setup({
+    -- ... Set up snippets ...
+    expand = { prepare = my_p, match = my_m, select = my_s, insert = my_i }
+  })
+<
+------------------------------------------------------------------------------
+                                                         *MiniSnippets.expand()*
+                         `MiniSnippets.expand`({opts})
+Expand snippet at cursor position
+
+Perform expand steps (see |MiniSnippets-glossary|).
+Initial raw snippets are taken from `config.snippets` in current buffer.
+Snippets from `vim.b.minisnippets_config` are appended to global snippet array.
+
+Parameters ~
+{opts} `(table|nil)` Options. Same structure as `expand` in |MiniSnippets.config|
+  and uses its values as default. There are differences in allowed values:
+  - Use `match = false` to have all buffer snippets as matches.
+  - Use `select = false` to always expand the best match (if any).
+  - Use `insert = false` to return all matches without inserting.
+
+  Note: `opts.insert` is called after ensuring Insert mode, removing snippet's
+  match region, and positioning cursor.
+
+Return ~
+`(table|nil)` If `insert` is `false`, an array of matched snippets (`expand.match`
+  output). Otherwise `nil`.
+
+Usage ~
+>lua
+  -- Match, maybe select, and insert
+  MiniSnippets.expand()
+
+  -- Match and force expand the best match (if any)
+  MiniSnippets.expand({ select = false })
+
+  -- Use all current context snippets as matches
+  MiniSnippets.expand({ match = false })
+
+  -- Get all matched snippets
+  local matches = MiniSnippets.expand({ insert = false })
+
+  -- Get all current context snippets
+  local all = MiniSnippets.expand({ match = false, insert = false })
+<
+
+See also ~
+|MiniSnippets.start_lsp_server()| to instead show loaded snippets
+  in (auto)completion engines (like |mini.completion|).
+
+------------------------------------------------------------------------------
+                                                       *MiniSnippets.gen_loader*
+                           `MiniSnippets.gen_loader`
+Generate snippet loader
+
+This is a table with function elements. Call to actually get a loader.
+
+Common features for all produced loaders:
+- Designed to work with |MiniSnippets-file-specification|.
+- Cache output by default, i.e. second and later calls with same input value
+  don't read file system. Different loaders from same generator share cache.
+  Disable by setting `opts.cache` to `false`.
+  To clear all cache, call |MiniSnippets.setup()|. For example:
+  `MiniSnippets.setup(MiniSnippets.config)`
+- Use |vim.notify()| to show problems during loading while trying to load as
+  much correctly defined snippet data as possible.
+  Disable by setting `opts.silent` to `true`.
+
+------------------------------------------------------------------------------
+                                           *MiniSnippets.gen_loader.from_lang()*
+                  `MiniSnippets.gen_loader.from_lang`({opts})
+Generate language loader
+
+Output loads files from `snippets/` subdirectories of |'runtimepath'| matching
+configured language patterns.
+See |MiniSnippets.gen_loader.from_runtime()| for runtime loading details.
+
+Language is taken from <lang> field (if present with string value) of `context`
+argument used in loader calls during "prepare" stage.
+This is compatible with |MiniSnippets.default_prepare()| and most snippet
+collection plugins.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible values:
+  - <lang_patterns> `(table)` - map from language to array of runtime patterns
+    used to find snippet files, as in |MiniSnippets.gen_loader.from_runtime()|.
+    Patterns will be processed in order. With |MiniSnippets.default_prepare()|
+    it means if snippets have same prefix, data from later patterns is used.
+    To interactively check the current language with default context, execute
+    `:=MiniSnippets.default_prepare({})` and see data in the second table.
+
+    Default pattern array (for non-empty language) is constructed as to read
+    `*.json` and `*.lua` files that are:
+    - Inside `snippets/` subdirectory named as language (files can be however
+      deeply nested).
+    - Named as language and is in `snippets/` directory (however deep).
+    Example for "lua" language: >lua
+        { 'lua/**/*.json', 'lua/**/*.lua', '**/lua.json', '**/lua.lua' }
+<
+    Add entry for `""` (empty string) as language to be sourced when `lang`
+    context is empty string (which is usually temporary scratch buffers).
+
+  - <cache> `(boolean)` - whether to use cached output. Default: `true`.
+    Note: caching is done per used runtime pattern, not `lang` value to allow
+    different `from_lang()` loaders to share cache.
+  - <silent> `(boolean)` - whether to hide non-error messages. Default: `false`.
+
+Return ~
+`(function)` Snippet loader.
+
+Usage ~
+>lua
+  -- Adjust language patterns
+  local latex_patterns = { 'latex/**/*.json', '**/latex.json' }
+  local lang_patterns = {
+    tex = latex_patterns, plaintex = latex_patterns,
+    -- Recognize special injected language of markdown tree-sitter parser
+    markdown_inline = { 'markdown.json' },
+  }
+  local gen_loader = require('mini.snippets').gen_loader
+  require('mini.snippets').setup({
+    snippets = {
+      gen_loader.from_lang({ lang_patterns = lang_patterns }),
+    },
+  })
+<
+------------------------------------------------------------------------------
+                                        *MiniSnippets.gen_loader.from_runtime()*
+           `MiniSnippets.gen_loader.from_runtime`({pattern}, {opts})
+Generate runtime loader
+
+Output loads files which match `pattern` inside `snippets/` directories from
+|'runtimepath'|. This is useful to simultaneously read several similarly
+named files from different sources. Order from |'runtimepath'| is preserved.
+
+Typical case is loading snippets for a language from files like `xxx.{json,lua}`
+but located in different `snippets/` directories inside |'runtimepath'|.
+- `<config>`/snippets/lua.json - manually curated snippets in user config.
+- `<path/to/installed/plugin>`/snippets/lua.json - from installed plugin.
+- `<config>`/after/snippets/lua.json - used to adjust snippets from plugins.
+  For example, remove some snippets by using prefixes and no body.
+
+Parameters ~
+{pattern} `(string)` Pattern of files to read. Can have wildcards as described
+  in |nvim_get_runtime_file()|. Example for "lua" language: `'lua.{json,lua}'`.
+{opts} `(table|nil)` Options. Possible fields:
+  - <all> `(boolean)` - whether to load from all matching runtime files.
+    Default: `true`.
+  - <cache> `(boolean)` - whether to use cached output. Default: `true`.
+    Note: caching is done per `pattern` value, which assumes that both
+    |'runtimepath'| value and snippet files do not change during Neovim session.
+    Caching this way gives significant speed improvement by reducing the need
+    to traverse file system on every snippet expand.
+  - <silent> `(boolean)` - whether to hide non-error messages. Default: `false`.
+
+Return ~
+`(function)` Snippet loader.
+
+------------------------------------------------------------------------------
+                                           *MiniSnippets.gen_loader.from_file()*
+              `MiniSnippets.gen_loader.from_file`({path}, {opts})
+Generate single file loader
+
+Output is a thin wrapper around |MiniSnippets.read_file()| which will skip
+warning if file is absent (other messages are still shown). Use it to load
+file which is not guaranteed to exist (like project-local snippets).
+
+Parameters ~
+{path} `(string)` Same as in |MiniSnippets.read_file()|.
+{opts} `(table|nil)` Same as in |MiniSnippets.read_file()|.
+
+Return ~
+`(function)` Snippet loader.
+
+------------------------------------------------------------------------------
+                                                      *MiniSnippets.read_file()*
+                    `MiniSnippets.read_file`({path}, {opts})
+Read file with snippet data
+
+Parameters ~
+{path} `(string)` Path to file with snippets. Can be relative.
+  See |MiniSnippets-file-specification| for supported file formats.
+{opts} `(table|nil)` Options. Possible fields:
+  - <cache> `(boolean)` - whether to use cached output. Default: `true`.
+    Note: Caching is done per full path only after successful reading.
+  - <silent> `(boolean)` - whether to hide non-error messages. Default: `false`.
+
+Return ~
+`(table|nil)` Array of snippets or `nil` if failed (also warn with |vim.notify()|
+  about the reason).
+
+------------------------------------------------------------------------------
+                                                *MiniSnippets.default_prepare()*
+             `MiniSnippets.default_prepare`({raw_snippets}, {opts})
+Default prepare
+
+Normalize raw snippets (as in `snippets` from |MiniSnippets.config|) based on
+supplied context:
+- Traverse and flatten nested arrays. Function loaders are executed with
+  `opts.context` as argument and output is processed recursively.
+- Ensure unique non-empty prefixes: later ones completely override earlier
+  ones (similar to how |ftplugin| and similar runtime design behave).
+  Empty string prefixes are all added (to allow inserting without matching).
+- Transform and infer fields:
+    - Multiply array `prefix` into several snippets with same body/description.
+      Infer absent `prefix` as empty string.
+    - Concatenate array `body` with `"\n"`. Do not infer absent `body` to have
+      it remove previously added snippet with the same prefix.
+    - Concatenate array `desc` with `"\n"`. Infer `desc` field from `description`
+      (for compatibility) or `body` fields, in that order.
+- Sort output by prefix.
+
+Unlike |MiniSnippets.gen_loader| entries, there is no output caching. This
+avoids duplicating data from `gen_loader` cache and reduces memory usage.
+It also means that every |MiniSnippets.expand()| call prepares snippets, which
+is usually fast enough. If not, consider manual caching: >lua
+
+  local cache = {}
+  local prepare_cached = function(raw_snippets)
+    local _, cont = MiniSnippets.default_prepare({})
+    local id = 'buf=' .. cont.buf_id .. ',lang=' .. cont.lang
+    if cache[id] then return unpack(vim.deepcopy(cache[id])) end
+    local snippets = MiniSnippets.default_prepare(raw_snippets)
+    cache[id] = vim.deepcopy({ snippets, cont })
+    return snippets, cont
+  end
+<
+Parameters ~
+{raw_snippets} `(table)` Array of snippet data as from |MiniSnippets.config|.
+{opts} `(table|nil)` Options. Possible fields:
+  - <context> `(any)` - Context used as an argument for callable snippet data.
+    Default: table with <buf_id> (current buffer identifier) and <lang> (local
+    language) fields. Language is computed from tree-sitter parser at cursor
+    (allows different snippets in injected languages), |'filetype'| otherwise.
+
+Return ~
+`(...)` Array of snippets and supplied context (default if none was supplied).
+
+------------------------------------------------------------------------------
+                                                  *MiniSnippets.default_match()*
+                `MiniSnippets.default_match`({snippets}, {opts})
+Default match
+
+Match snippets based on the line before cursor.
+
+Tries two matching approaches consecutively:
+- Find exact snippet prefix (if present and non-empty) to the left of cursor.
+  It should also be preceded with a byte that matches `pattern_exact_boundary`.
+  In case of any match, return the one with the longest prefix.
+- Match fuzzily snippet prefixes against the base (text to the left of cursor
+  extracted via `opts.pattern_fuzzy`). Matching is done via |matchfuzzy()|.
+  Empty base results in all snippets being matched. Return all fuzzy matches.
+
+Parameters ~
+{snippets} `(table)` Array of snippets which can be matched.
+{opts} `(table|nil)` Options. Possible fields:
+  - <pattern_exact_boundary> `(string)` - Lua pattern for the byte to the left
+    of exact match to accept it. Line start is matched against empty string;
+    use `?` quantifier to allow it as boundary.
+    Default: `[%s%p]?` (accept only whitespace and punctuation as boundary,
+    allow match at line start).
+    Example: prefix "l" matches in lines `l`, `_l`, `x l`; but not `1l`, `ll`.
+  - <pattern_fuzzy> `(string)` - Lua pattern to extract base to the left of
+    cursor for fuzzy matching. Supply empty string to skip this step.
+    Default: `'%S*'` (as many as possible non-whitespace; allow empty string).
+
+Return ~
+`(table)` Array of matched snippets ordered from best to worst match.
+
+Usage ~
+>lua
+  -- Accept any exact match
+  MiniSnippets.default_match(snippets, { pattern_exact_boundary = '.?' })
+
+  -- Perform fuzzy match based only on alphanumeric characters
+  MiniSnippets.default_match(snippets, { pattern_fuzzy = '%w*' })
+<
+------------------------------------------------------------------------------
+                                                 *MiniSnippets.default_select()*
+          `MiniSnippets.default_select`({snippets}, {insert}, {opts})
+Default select
+
+Show snippets as |vim.ui.select()| items and insert the chosen one.
+For best interactive experience requires `vim.ui.select()` to work from Insert
+mode (be properly called and restore Insert mode after choice).
+This is the case for at least |MiniPick.ui_select()| and Neovim's default.
+
+Parameters ~
+{snippets} `(table)` Array of snippets (as an output of `config.expand.match`).
+{insert} `(function|nil)` Function to insert chosen snippet (passed as the only
+  argument). Expected to remove snippet's match region (if present as a field)
+  and ensure proper cursor position in Insert mode.
+  Default: |MiniSnippets.default_insert()|.
+{opts} `(table|nil)` Options. Possible fields:
+  - <insert_single> `(boolean)` - whether to skip |vim.ui.select()| for `snippets`
+    with a single entry and insert it directly. Default: `true`.
+
+------------------------------------------------------------------------------
+                                                 *MiniSnippets.default_insert()*
+                `MiniSnippets.default_insert`({snippet}, {opts})
+Default insert
+
+Prepare for snippet insert and do it:
+- Ensure Insert mode.
+- Delete snippet's match region (if present as <region> field). Ensure cursor.
+- Parse snippet body with |MiniSnippets.parse()| and enabled `normalize`.
+  In particular, evaluate variables, ensure final node presence and same
+  text for nodes with same tabstops. Stop if not able to.
+- Insert snippet at cursor:
+    - Add snippet's text. Lines are split at "\n".
+      Indent and left comment leaders (inferred from |'commentstring'| and
+      |'comments'|) of current line are repeated on the next.
+      Tabs ("\t") are expanded according to |'expandtab'| and |'shiftwidth'|.
+    - If there is an actionable tabstop (not final), start snippet session.
+
+# Session life cycle ~
+*MiniSnippets-session*
+
+- Start with cursor at first tabstop. If there are linked tabstops, cursor
+  is placed at start of reference node (see |MiniSnippets-glossary|).
+  All tabstops are visualized with dedicated highlight groups (see "Highlight
+  groups" section in |mini.snippets|).
+  Empty tabstops are visualized with inline virtual text ("•"/"∎" for
+  regular/final tabstops) meaning that it is not an actual text in the
+  buffer and will be removed after session is stopped.
+
+- Decide whether you want to replace the placeholder. If not, jump to next or
+  previous tabstop. If yes, edit it: add new and/or delete already added text.
+  While doing so, several things happen in all linked tabstops (if any):
+
+    - After first typed character the placeholder is removed and highlighting
+      changes from `MiniSnippetsCurrentReplace` to `MiniSnippetsCurrent`.
+    - Text in all tabstop nodes is synchronized with the reference one.
+      Relative indent of reference tabstop's text is preserved: all but first
+      lines in linked tabstops are reindented based on the first line indent.
+      Note: text sync is forced only for current tabstop (for performance).
+
+- Jump with <C-l> / <C-h> to next / previous tabstop. Exact keys can be
+  adjusted in |MiniSnippets.config| `mappings`.
+  See |MiniSnippets.session.jump()| for jumping details.
+
+- If tabstop has choices, all of them are shown after each jump and deleting
+  tabstop text. It is done with |complete()|, so use <C-n> / <C-p> to select
+  next / previous choice. Type text to narrow down the list.
+  Works best when |'completeopt'| option contains `menuone` and `noselect` flags.
+  Note: deleting character hides the list due to how |complete()| works;
+  delete whole tabstop text (for example with one or more |i_CTRL-W|) for
+  full list to reappear.
+
+- Nest another session by expanding snippet in the same way as without
+  active session (can be even done in another buffer). If snippet has no
+  actionable tabstop, text is just inserted. Otherwise start nested session:
+
+    - Suspend current session: hide highlights, keep text change tracking.
+    - Start new session and act as if it is the only one (edit/jump/nest).
+    - When ready (possibly after even more nested sessions), stop the session.
+      This will resume previous one: sync text for its current tabstop and
+      show highlighting.
+      The experience of text synchronization only after resuming session is
+      similar to how editing in |visual-block| mode works.
+      Nothing else (like cursor/mode/buffer) is changed for a smoother
+      automated session stop.
+
+  Notes about the choice of the "session stack" approach to nesting over more
+  common "merge into single session" approach:
+  - Does not overload with highlighting.
+  - Allows nested sessions in different buffers.
+  - Doesn't need a complex logic of injecting one session into another.
+
+- Repeat edit/jump/nest steps any number of times.
+
+- Stop. It can be done in two ways:
+
+    - Manually by pressing <C-c> or calling |MiniSnippets.session.stop()|.
+      Exact key can be adjusted in |MiniSnippets.config| `mappings`.
+    - Automatically: any text edit or switching to Normal mode stops session
+      if final tabstop (`$0`) is current. Its presence is ensured after insert.
+      Not stopping session right away after jumping to final mode (as most
+      other snippet plugins do) allows going back to other tabstops in case
+      of a late missed typo. Wrapping around the edge during jumping also
+      helps with that.
+      If current tabstop is not final, exiting into Normal mode for quick edit
+      outside of snippets range (or carefully inside) is fine. Later get back
+      into Insert mode and jump to next tabstop or manually stop session.
+  See |MiniSnippets-examples| for how to set up custom stopping rules.
+
+Use |MiniSnippets.session.get()| to get data about active/nested session(s).
+Use |MiniSnippets.session.jump()| / |MiniSnippets.session.stop()| in mappings.
+
+What is allowed but not officially supported/recommended:
+
+- Editing text within snippet range but outside of session life cycle. Mostly
+  behaves as expected, but may harm tracking metadata (|extmarks|).
+  In general anything but deleting tabstop range should be OK.
+  Text synchronization of current tabstop would still be active.
+
+# Events ~
+*MiniSnippets-events*
+
+General session activity (autocommand data contains <session> field):
+- `MiniSnippetsSessionStart` - after a session is started.
+- `MiniSnippetsSessionStop` - before a session is stopped.
+
+Nesting session activity (autocommand data contains <session> field):
+- `MiniSnippetsSessionSuspend` - before a session is suspended.
+- `MiniSnippetsSessionResume` - after a session is resumed.
+
+Jumping between tabstops (autocommand data contains <tabstop_from> and
+<tabstop_new> fields):
+- `MiniSnippetsSessionJumpPre` - before jumping to a new tabstop.
+- `MiniSnippetsSessionJump` - after jumping to a new tabstop.
+
+Parameters ~
+{snippet} `(table)` Snippet table. Field <body> is mandatory.
+{opts} `(table|nil)` Options. Possible fields:
+  - <empty_tabstop> `(string)` - used to visualize empty regular tabstops.
+    Default: "•".
+  - <empty_tabstop_final> `(string)` - used to visualize empty final tabstop(s).
+    Default: "∎".
+  - <lookup> `(table)` - passed to |MiniSnippets.parse()|. Use it to adjust
+    how variables are evaluated. Default: `{}`.
+
+------------------------------------------------------------------------------
+                                                          *MiniSnippets.session*
+                             `MiniSnippets.session`
+Work with snippet session from |MiniSnippets.default_insert()|
+
+------------------------------------------------------------------------------
+                                                    *MiniSnippets.session.get()*
+                       `MiniSnippets.session.get`({all})
+Get data about active session
+
+Parameters ~
+{all} `(boolean|nil)` Whether to return array with the whole session stack.
+  Default: `false`.
+
+Return ~
+`(table)` Single table with session data (if `all` is `false`) or array of them.
+  Session data contains the following fields:
+   - <buf_id> `(number)` - identifier of session's buffer.
+   - <cur_tabstop> `(string)` - identifier of session's current tabstop.
+   - <extmark_id> `(number)` - |extmark| identifier which track session range.
+   - <insert_args> `(table)` - |MiniSnippets.default_insert()| arguments used to
+     create the session. A table with <snippet> and <opts> fields.
+   - <nodes> `(table)` - parsed array of snippet nodes which is kept up to date
+     during session. Has the structure of a normalized |MiniSnippets.parse()|
+     output, plus every node contains `extmark_id` field with |extmark| identifier
+     which can be used to get data about the current node state.
+   - <ns_id> `(number)` - |namespace| identifier for all session's extmarks.
+   - <tabstops> `(table)` - data about session's tabstops. Fields are string
+     tabstop identifiers and values are tables with the following fields:
+       - <is_visited> `(boolean)` - whether tabstop was visited.
+       - <next> `(string)` - identifier of the next tabstop.
+       - <prev> `(string)` - identifier of the previous tabstop.
+
+------------------------------------------------------------------------------
+                                                   *MiniSnippets.session.jump()*
+                    `MiniSnippets.session.jump`({direction})
+Jump to next/previous tabstop
+
+Make next/previous tabstop be current. Executes the following steps:
+- Mark current tabstop as visited.
+- Find the next/previous tabstop id assuming they are sorted as numbers.
+  Tabstop "0" is always last. Search is wrapped around the edges: first and
+  final tabstops are next/previous for one another.
+- Focus on target tabstop:
+    - Ensure session's buffer is current.
+    - Adjust highlighting of affected nodes.
+    - Set cursor at tabstop's reference node (first node among linked).
+      Cursor is placed on left edge if tabstop has not been edited yet (so
+      typing text replaces placeholder), on right edge otherwise (to update
+      already edited text).
+    - Show all choices for tabstop with choices. Navigating through choices
+      will update tabstop's text.
+
+Parameters ~
+{direction} `(string)` One of "next" or "prev".
+
+------------------------------------------------------------------------------
+                                                   *MiniSnippets.session.stop()*
+                         `MiniSnippets.session.stop`()
+Stop (only) active session
+
+To stop all nested sessions use the following code: >lua
+
+  while MiniSnippets.session.get() do
+    MiniSnippets.session.stop()
+  end
+<
+------------------------------------------------------------------------------
+                                                          *MiniSnippets.parse()*
+                  `MiniSnippets.parse`({snippet_body}, {opts})
+Parse snippet
+
+Parameters ~
+{snippet_body} `(string|table)` Snippet body as string or array of strings.
+  Should follow |MiniSnippets-syntax-specification|.
+{opts} `(table|nil)` Options. Possible fields:
+  - <normalize> `(boolean)` - whether to normalize nodes:
+    - Evaluate variable nodes and add output as a `text` field.
+      If variable is not set, `text` field is `nil`.
+      Values from `opts.lookup` are preferred over evaluation output.
+      See |MiniSnippets-syntax-specification| for more info about variables.
+    - Add `text` field for tabstops present in `opts.lookup`.
+    - Ensure every node contains exactly one of `text` or `placeholder` fields.
+      If there are none, add default `placeholder` (one text node with first
+      choice or empty string). If there are both, remove `placeholder` field.
+    - Ensure present final tabstop: append to end if absent.
+    - Ensure that nodes for same tabstop have same placeholder. Use the one
+      from the first node.
+    Default: `false`.
+  - <lookup> `(table)` - map from variable/tabstop (string) name to its value.
+    Default: `{}`.
+
+Return ~
+`(table)` Array of nodes. Node is a table with fields depending on node type:
+  - Text node:
+    - <text> `(string)` - node's text.
+  - Tabstop node:
+    - <tabstop> `(string)` - tabstop identifier.
+    - <text> `(string|nil)` - tabstop value (if present in <lookup>).
+    - <placeholder> `(table|nil)` - array of nodes to be used as placeholder.
+    - <choices> `(table|nil)` - array of string choices.
+    - <transform> `(table|nil)` - array of transformation string parts.
+  - Variable node:
+    - <var> `(string)` - variable name.
+    - <text> `(string|nil)` - variable value.
+    - <placeholder> `(table|nil)` - array of nodes to be used as placeholder.
+    - <transform> `(table|nil)` - array of transformation string parts.
+
+------------------------------------------------------------------------------
+                                               *MiniSnippets.start_lsp_server()*
+                    `MiniSnippets.start_lsp_server`({opts})
+Start completion LSP server
+
+This starts (|vim.lsp.start()|) an LSP server with the purpose of displaying
+snippets in (auto)completion engines (|mini.completion| in particular).
+The server:
+- Only implements `textDocument/completion` method which prepares and matches
+  snippets at cursor (via |MiniSnippets.expand()|).
+- Auto-attaches to all loaded buffers by default.
+
+Parameters ~
+{opts} `(table|nil)` Options. Possible fields:
+  - <before_attach> `(function)` - function executed before every attach to
+    the buffer. Takes buffer id as input and can return `false` (not `nil`) to
+    cancel attaching to the buffer. Default: attach to loaded normal buffers.
+  - <match> `(false|function)` - value of `opts.match` forwarded to
+    the |MiniSnippets.expand()| when computing completion candidates.
+    Supply `false` to not do matching at cursor, return all available snippets
+    in cursor context, and rely on completion engine to match and sort items.
+    Default: `nil` (equivalent to |MiniSnippets.default_match()|).
+  - <server_config> `(table)` - server config to be used as basis for first
+    argument to |vim.lsp.start()| (`cmd` will be overridden). Default: `{}`.
+  - <triggers> `(table)` - array of trigger characters to be used as
+    `completionProvider.triggerCharacters` server capability. Default: `{}`.
+
+Return ~
+`(integer|nil)` Identifier of started LSP server.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: