Image Preview Extra

ui.image-preview enables Snacks image rendering. It can preview image files and render supported document images in terminals that understand the Kitty graphics protocol.

Enable it

-- ~/.config/blak/lua/blak/user.lua
return {
  extras = {
    enabled = {
      "ui.image-preview",
    },
  },
}

Or enable it interactively:

:BlakExtras enable ui.image-preview

What it adds

Surface	Contribution
Snacks	image.enabled = true
Terminal support	Kitty, Ghostty, WezTerm, and tmux passthrough where available
External tools	ImageMagick (magick or identify), required for every image

Requirements

Install ImageMagick before enabling the extra:

brew install imagemagick        # macOS
sudo apt install imagemagick    # Debian/Ubuntu

Snacks reads every image’s size with ImageMagick’s identify, PNG included. Without it, opening any image shows Image Conversion Failed: identify even though :checkhealth snacks says PNG files still work. PDFs need Ghostscript (gs), LaTeX math needs tectonic or pdflatex, and Mermaid needs mmdc.

The terminal must speak the Kitty graphics protocol. Other terminals get a placeholder buffer instead of the image.

Configure image rendering

Add Snacks image options under snacks.image:

return {
  extras = {
    enabled = { "ui.image-preview" },
  },
  snacks = {
    image = {
      force = false,
      doc = {
        enabled = true,
        inline = true,
        float = true,
        max_width = 80,
        max_height = 40,
      },
      img_dirs = { "img", "images", "assets", "static", "public" },
    },
  },
}

If inline rendering behaves poorly in your terminal, keep previews in floats:

return {
  extras = {
    enabled = { "ui.image-preview" },
  },
  snacks = {
    image = {
      doc = {
        inline = false,
        float = true,
      },
    },
  },
}

Terminal notes

Snacks can auto-detect supported terminals. If your environment is unusual, set one of Snacks’ environment flags before launching Neovim:

SNACKS_GHOSTTY=true blak

For tmux, make sure passthrough is enabled if images do not display.

Verify it

Run:

:checkhealth snacks
:BlakDoctor

Snacks.image should report setup {enabled}, a detected terminal, and a non-zero cell size. Then open a PNG or a Markdown file with an image reference.

Image buffers are read-only. If :q asks to save one, answering yes does not write the file; Snacks intercepts writes for image paths.