Preview options

💻 Preview options

preview = {
    --- When `true`, newly attached buffers
    --- show preview.
    ---@type boolean
    enable = true,
    --- When `true`, hybrid mode is enabled
    --- on newly attached buffers.
    ---@type boolean
    enable_hybrid_mode = true,

    --- List of filetypes to enable preview
    --- for.
    ---@type string[]
    filetypes = { "help" },
    --- List of 'buftype' to ignore.
    ---@type string[]
    ignore_buftypes = {},
    --- Additional condition for attaching
    --- to new buffers.
    ---@type fun(buffer: integer): boolean
    condition = nil,

    ---Modes where previews are shown.
    ---@type string[]
    modes = { "n", "no", "c" },
    --- Modes where hybrid mode is used.
    ---@type string[]
    hybrid_modes = {},
    --- Enables linewise-hybrid mode.
    ---@type boolean
    linewise_hybrid_mode = false,
    --- Items that won't be affected by
    --- `hybrid mode`.
    ---@type preview.ignore
    ignore_previews = {},

    --- Debounce delay for updating previews.
    ---@type integer
    debounce = 150,
    --- Maximum number of lines a buffer can
    --- have for it to be rendered entirely.
    ---@type integer
    max_buf_lines = 1000,

    --- Number of lines above & below the cursor
    --- to parse and draw.
    ---@type [ integer, integer ]
    draw_range = { 2 * vim.o.lines, 2 * vim.o.lines },
    --- Number of lines above & below the cursor
    --- that will be affected by `hybrid mode.
    ---@type [ integer, integer ]
    edit_range = { 0, 0 },

    --- Callback functions.
    ---@type { [string]: function }
    callbacks = {},

    --- Window options for the splitview window.
    ---@type table.
    splitview_winopts = {},
    --- Window options for the overlay window in
    --- `:Help`.
    ---@type table.
    overlay_winopts = {},
    --- Window options for the preview window in
    --- `:Help`.
    ---@type table.
    preview_winopts = {},

    --- Icon provider for code blocks.
    ---@field icon_provider?
    ---| "internal" Internal icon provider.
    ---| "devicons" `nvim-web-devicons` as icon provider.
    ---| "mini" `mini.icons` as icon provider.
    icon_provider = "internal"
}

enable

• Type: boolean

When true, attached buffers have their preview enabled.

Tip

You can set this to false in case you manually enable previews(:Helpview toggle).

enable_hybrid_mode

• Type: boolean

When true, attached buffers have hybrid mode enabled in their preview.

Tip

You can set this to false in case you use hybrid mode only sometimes(:Helpview hybridToggle).

filetypes

• Type: string[]

List of filetypes where this plugin will be enabled on.

ignore_buftypes

• Type: string[]

List of buftype to ignore.

condition

• Type: fun(buffer: integer): boolean

A function to determine if the plugin should be enabled on a buffer.

Note

This is done after matching filetypes & ignore_buftypes.

condition = function (buffer)
    local ft, bt = vim.bo[buffer].ft, vim.bo[buffer].bt;

    --- Only attaches to any kind of help
    --- files and `nofile` buffers(for the
    --- other filetypes).
    if ft == "help" then
        return true;
    elseif bt ~= "nofile" then
        return true;
    else
        return false;
    end
end

modes

• Type: string[]

Modes where previews will be shown.

hybrid_modes

• Type: string[]

Preview modes where hybrid mode is used.

Important

The mode must also be in modes to take effect.

linewise_hybrid_mode

• Type: boolean

Normal hybrid mode	Linewise hybrid mode

When true, hybrid mode clears the lines around the cursor instead of the range of the node under the cursor.

ignore_previews

• Type: preview.ignore

Normal hybrid mode	Hybrid mode with ignore_previews

--- Controls which items are affected by `hybrid_mode`.
---@class preview.ignore
---
---@field vimdoc? ignore_vimdoc[]
ignore_previews = {}

---@alias ignore_vimdoc
---| "arguments"
---| "code_blocks"
---| "headings"
---| "highlight_groups"
---| "horizontal_rules"
---| "inline_codes"
---| "keycodes"
---| "modelines"
---| "notes"
---| "optionlinks"
---| "tags"
---| "taglinks"
---| "urls"
---
---| "!arguments"
---| "!code_blocks"
---| "!headings"
---| "!highlight_groups"
---| "!horizontal_rules"
---| "!inline_codes"
---| "!keycodes"
---| "!modelines"
---| "!notes"
---| "!optionlinks"
---| "!tags"
---| "!taglinks"
---| "!urls"

Controls which items are affected by hybrid mode.

Items affected by hybrid mode will show their raw version when inside edit_range.

Each language can be a list of option names. Possible values are,

• vimdoc,

  • arguments
  • code_blocks
  • headings
  • highlight_groups
  • horizontal_rules
  • inline_codes
  • keycodes
  • modelines
  • notes
  • optionlinks
  • tags
  • taglinks
  • urls

Tip

You can add a ! before an option name to prevent it from being affected by hybrid mode.

--- Hybrid mode will no longer affect
--- code blocks.
ignore_previews = {
    vimdoc = { "!code_blocks" }
}

debounce

• Type: integer

Debounce delay for updating previews.

Tip

You can reduce this value if you want faster updates to the preview.

max_buf_lines

• Type: integer

Maximum number of lines a buffer can have for it to be rendered entirely.

Larger buffers will only render things around the cursor(s).

draw_range

• Type: [ integr, integer ]

Range of lines above & below the cursor to render on larger buffers.

edit_range

• Type: [ integr, integer ]

Range of lines above & below the cursor that are affected by hybrid mode.

callbacks

• Type: { [string]: function }

Callback functions.

--- Callback functions for specific events.
---@class preview.callbacks
---
--- Called when attaching to a buffer.
---@field on_attach? fun(buf: integer, wins: integer[]): nil
--- Called when detaching from a buffer.
---@field on_detach? fun(buf: integer, wins: integer[]): nil
---
--- Called when disabling preview of a buffer.
--- Also called when opening `splitview`.
---@field on_disable? fun(buf: integer, wins: integer[]): nil
--- Called when enabling preview of a buffer.
--- Also called when disabling `splitview`.
---@field on_enable? fun(buf: integer, wins: integer[]): nil
---
--- Called when disabling hybrid mode in a buffer.
--- > Called after `on_attach` when attaching to a buffer.
--- > Called after `on_disable`.
---@field on_hybrid_disable? fun(buf: integer, wins: integer[]): nil
--- Called when enabling hybrid mode in a buffer.
--- > Called after `on_attach`(if `hybrid_mod` is disabled).
--- > Called after `on_enable`.
---@field on_hybrid_enable? fun(buf: integer, wins: integer[]): nil
---
--- Called when changing VIM-modes(only on active buffers).
---@field on_mode_change? fun(buf: integer, wins: integer[], mode: string): nil
---
--- Called before closing splitview.
---@field on_splitview_close? fun(source: integer, preview_buf: integer, preview_win: integer): nil
--- Called when opening splitview.
---@field on_splitview_open? fun(source: integer, preview_buf: integer, preview_win: integer): nil
---
--- Called when opening `:Help`(:H).
---@field on_help_open? fun(preview_buf: integer, preview_win: integer, overlay_buf: integer, overlay_win: integer): nil

A short description of what each parameter represents,

• buf Buffer where the callback is being run on.

• wins List of windows that contain buf.

• mode VIM mode short-hand(e.g. "n", "i"). Output of vim.api.nvim_get_mode().mode.

• source Source buffer for splitview.

• preview_buf Buffer containing the preview of splitview(or :Help).

• preview_win Window containing the preview of splitview(or :Help).

• overlay_buf Overlay windows buffer(may be nil).

• overlay_win Overlay window(shown below the :Help window).

splitview_winopts

• Type: table

Window options for splitview. See {opts} in :h nvim_open_win().

overlay_winopts

• Type: table

Window options for the overly window of :Help. See {opts} in :h nvim_open_win().

preview_winopts

• Type: table

Window options for the preview window of :Help. See {opts} in :h nvim_open_win().

icon_provider

• Type: "devicons | "internal" | "mini"
• Dynamic: true
• Default: "internal"

Note

You will need to install the external icon providers to use them!

Changes the icon provider used for drawing icons. Currently supported providers are,

--- Icon provider.
---@field icon_provider?
---| "internal" Internal icon provider.
---| "devicons" `nvim-web-devicons` as icon provider.
---| "mini" `mini.icons` as icon provider.
icon_provider = "internal",

Here's a simple comparison,

Feature	devicons	mini	internal
Icon support	many	many	limited
Dynamic colors	no	partial	yes
External	yes	yes	no