Can the snacks.image plugin's inline preview mode (non-floating mode) support smooth scrolling?

[lsw9521]

If snacks.image could add just one more feature, I think I’d never need to search for another markdown editor for the rest of my life! The plugin’s inline image preview is already fantastic.

But there’s one small issue: whenever I move through the document using j or k, if the cursor passes over an image element, the image suddenly appears and the document auto-scrolls to reveal the full image.

This well-meaning auto-scroll behavior ends up conflicting with visual expectations and operational control—it completely breaks the immersive experience of editing.
It makes you feel like you’ve lost full control over Vim, because during normal editing, you’d never expect that pressing a single j key would cause the entire page to scroll half a screen and make familiar content suddenly disappear from view.

I know the float preview mode avoids this kind of unexpected scrolling, but that’s not the effect I’m looking for either.
What I really want is: in inline rendering mode, when scrolling with j and k, image elements should also scroll “line by line.”

Since we already have a configuration that maps image height to a certain number of “lines,” each press of j or k should scroll by 1/n of the image’s height, rather than triggering the full image to appear all at once.
This would prevent the sudden visual jump and align perfectly with the user’s mental expectation of scrolling behavior.

Additionally, it would be great to mark the current line position in the area where the editor normally displays line numbers and icons—on the left side of the image.
That way, users can visually track the cursor’s position even when navigating through image blocks.

[drowning-cat]

Forget it. Inline images are added via virtual_text, kind of like diagnostic errors are displayed. As far as I know, in Neovim you can’t move the cursor over virtual_text, not even with gj or gk. If you try to do this by inserting empty lines into the file, you’d actually be changing the file itself. Who wants weird empty lines in their files? I sure don’t. So yeah, it’s just not doable.

[lsw9521]

thank you ！

[lsw9521]

Hello! I'm back again! And you're absolutely right — we can't place anything on top of the inline images rendered by snacks.image, whether it's the image area itself or the corresponding icon area on the left. This completely kills my idea of simulating the cursor's current line position within the image area!

However, smooth scrolling of images while navigating the document with the j and k keys is actually achievable. By checking the visibility status of the image's line and the line immediately following it within Neovim's viewport, we can determine whether the image is fully visible (except for the initial case when the image hasn't fully rendered yet). This method doesn't rely on the image's height and doesn't modify the buffer in any way!

When the image isn't fully visible, we remap the j and k keys to scroll the document up or down by one line. Once the image is fully visible, the keys revert to their original behavior. This allows the image to be gently scrolled into view from the top or bottom edge of the viewport — one line at a time — instead of suddenly jumping into view and startling the user!

In fact, by calculating the positions of the image's line and its next line, we can even infer how many lines tall the image is. But as mentioned earlier, we can't display anything over the inline image area, which prevents us from simulating the effect of the cursor "walking" across the image using j and k. Still, smooth scrolling is at least usable!

Below is the AI-assisted code. To use it, simply import the file with require("extras.scroll_image").

-- ~/.config/nvim/lua/extras/scroll_image.lua
local api = vim.api
local ts = vim.treesitter

-- Stores image line metadata per buffer
local image_lines = {}
-- Tracks whether a buffer contains any images
local has_images = {}

-- Get the visible line range in the current window (1-based)
local function visible_range()
  return vim.fn.line('w0'), vim.fn.line('w$')
end

-- Check if the cursor is on an image start or end line, and return the image info
local function cursor_on_image(bufnr)
  local row = api.nvim_win_get_cursor(0)[1]
  for _, img in ipairs(image_lines[bufnr] or {}) do
    if row == img.line or row == img.next then
      return img, row
    end
  end
end

-- Determine whether the image is partially visible in the viewport
local function image_partial(img)
  local w0, w1 = visible_range()
  return img.line >= w0 and img.line <= w1 and img.next > w1
      or img.next >= w0 and img.next <= w1 and img.line < w0
end

-- Set custom scroll key mappings for 'j' and 'k'
local function set_scroll_keys(bufnr)
  vim.keymap.set('n', 'j', function()
    if vim.v.count > 0 then return vim.v.count .. 'j' end
    if not has_images[bufnr] then return 'j' end

    local img, row = cursor_on_image(bufnr)
    -- If cursor is on image start line and image is not fully visible, scroll down one line
    if img and row == img.line then
      if image_partial(img) then
        return api.nvim_replace_termcodes('<C-E>', true, false, true)
      end
    end
    return 'j'
  end, { expr = true, noremap = true, buffer = bufnr })

  vim.keymap.set('n', 'k', function()
    if vim.v.count > 0 then return vim.v.count .. 'k' end
    if not has_images[bufnr] then return 'k' end

    local img, row = cursor_on_image(bufnr)
    -- If cursor is on image end line and image is not fully visible, scroll up one line
    if img and row == img.next then
      if image_partial(img) then
        return api.nvim_replace_termcodes('<C-Y>', true, false, true)
      end
    end
    return 'k'
  end, { expr = true, noremap = true, buffer = bufnr })
end

-- Restore default scroll key mappings
local function clear_scroll_keys(bufnr)
  vim.keymap.set('n', 'j', 'j', { noremap = true, buffer = bufnr })
  vim.keymap.set('n', 'k', 'k', { noremap = true, buffer = bufnr })
end

-- Update image line metadata and apply scroll key logic
local function update_image_lines(bufnr)
  -- Only operate on markdown buffers
  if vim.bo[bufnr].filetype ~= 'markdown' then
    image_lines[bufnr] = nil
    has_images[bufnr] = false
    clear_scroll_keys(bufnr)
    return
  end

  -- Try to get Treesitter parser for markdown_inline
  local okp, parser = pcall(ts.get_parser, bufnr, 'markdown_inline')
  if not okp then return end

  -- Try to parse image nodes using Treesitter query
  local okq, query = pcall(ts.query.parse, 'markdown_inline', '((image) @img)')
  if not okq then return end

  local lines = {}

  -- Iterate over all image nodes and record their start and end lines
  for _, tree in ipairs(parser:parse()) do
    for _, node in query:iter_captures(tree:root(), bufnr, 0, -1) do
      local sr = node:range()
      sr = sr + 1 -- Convert 0-based to 1-based line number
      lines[#lines + 1] = { line = sr, next = sr + 1 }
    end
  end

  image_lines[bufnr] = lines
  has_images[bufnr] = #lines > 0

  -- Apply or clear scroll key mappings based on image presence
  if has_images[bufnr] then
    set_scroll_keys(bufnr)
  else
    clear_scroll_keys(bufnr)
  end
end

-- Automatically update image metadata and scroll mappings on buffer events
api.nvim_create_autocmd({ 'BufEnter', 'TextChanged', 'TextChangedI', 'InsertLeave' }, {
  callback = function(args)
    update_image_lines(args.buf)
  end,
})

[lsw9521]

I asked the AI to refine the code again to fix a bug where, upon opening a document for the first time, images hadn't finished rendering yet—causing the j and k keys to skip over image regions too quickly, and then the images would suddenly pop in.

The current solution checks whether the image's start and end lines are visually adjacent to determine if rendering should be delayed. It only waits for images that are confirmed to exist locally; network images or invalid local paths are excluded from the wait logic to prevent the editor from freezing due to network latency or missing files.

The entire module only loads when a markdown file is opened. For me, the behavior is now nearly satisfactory.

Below is the latest code and usage guide.

Note: All logic depends on one prerequisite—inline rendering mode must be enabled in snacks.image.

-- .config/nvim/init.lua
require("config.autocmd")

-- .config/nvim/lua/config/autocmd.lua
vim.api.nvim_create_autocmd('FileType', {
  pattern = 'markdown',
  callback = function(args)
    require('extras.scroll_image').setup(args.buf)
  end,
})

-- .config/nvim/lua/extras/scroll_image.lua
local M = {}

function M.setup(bufnr)
  local api = vim.api
  local ts = vim.treesitter
  bufnr = bufnr or api.nvim_get_current_buf()

  local image_lines = {}
  local has_images = false

  local function visible_range()
    return vim.fn.line('w0'), vim.fn.line('w$')
  end

  local function cursor_on_image()
    local row = api.nvim_win_get_cursor(0)[1]
    for _, img in ipairs(image_lines) do
      if row == img.line or row == img.next then
        return img, row
      end
    end
  end

  local function image_partial(_, img)
    local w0, w1 = visible_range()
    return (img.line >= w0 and img.line <= w1 and img.next > w1)
        or (img.next >= w0 and img.next <= w1 and img.line < w0)
  end

  local function get_image_path(buf, line_nr)
    local line = api.nvim_buf_get_lines(buf, line_nr - 1, line_nr, false)[1] or ""
    local inner = line:match("%!%[[^%]]*%]%((.-)%)")
    if not inner then return nil end
    inner = inner:gsub("^%s+", ""):gsub("%s+$", "")

    local angle = inner:match("^<([^>]+)>$")
    local raw = angle or inner

    local url = raw:match("^([^%s]+)")
    if not url or url == "" then return nil end

    url = url:gsub("%%(%x%x)", function(h)
      return string.char(tonumber(h, 16))
    end)

    return url
  end

  local function is_abs_path(p)
    return p:match("^/") or p:match("^%a:[/\\]") ~= nil
  end

  local function path_join(a, b)
    if a:sub(-1) == "/" or a:sub(-1) == "\\" then return a .. b end
    return a .. "/" .. b
  end

  local function is_local_existing_image(buf, img)
    local path = get_image_path(buf, img.line)
    if not path or path == "" then
      return false
    end
    if path:match("^[%a][%w+%-%.]*://") then
      return false
    end

    local expanded = vim.fn.expand(path)

    local abs
    if is_abs_path(expanded) then
      abs = expanded
    else
      local base = vim.fn.fnamemodify(api.nvim_buf_get_name(buf), ":p:h")
      abs = path_join(base, expanded)
    end

    return vim.fn.filereadable(abs) == 1
  end

  local function image_loading(buf, img)
    if not is_local_existing_image(buf, img) then
      return false
    end

    local winid = api.nvim_get_current_win()
    local pos_start = vim.fn.screenpos(winid, img.line, 1) or {}
    local pos_next  = vim.fn.screenpos(winid, img.next, 1) or {}

    if not pos_start.row or not pos_next.row then
      return true
    end

    return (pos_next.row - pos_start.row) == 1
  end

  local function set_scroll_keys()
    vim.keymap.set('n', 'j', function()
      if vim.v.count > 0 then return vim.v.count .. 'j' end
      if not has_images then return 'j' end
      local img, row = cursor_on_image()
      if img and row == img.line and (image_loading(bufnr, img) or image_partial(bufnr, img)) then
        return api.nvim_replace_termcodes('<C-E>', true, false, true)
      end
      return 'j'
    end, { expr = true, noremap = true, buffer = bufnr })

    vim.keymap.set('n', 'k', function()
      if vim.v.count > 0 then return vim.v.count .. 'k' end
      if not has_images then return 'k' end
      local img, row = cursor_on_image()
      if img and row == img.next and (image_loading(bufnr, img) or image_partial(bufnr, img)) then
        return api.nvim_replace_termcodes('<C-Y>', true, false, true)
      end
      return 'k'
    end, { expr = true, noremap = true, buffer = bufnr })
  end

  local function clear_scroll_keys()
    vim.keymap.set('n', 'j', 'j', { noremap = true, buffer = bufnr })
    vim.keymap.set('n', 'k', 'k', { noremap = true, buffer = bufnr })
  end

  local function update_image_lines()
    local okp, parser = pcall(ts.get_parser, bufnr, 'markdown_inline')
    if not okp then
      image_lines = {}
      has_images = false
      clear_scroll_keys()
      return
    end
    local okq, query = pcall(ts.query.parse, 'markdown_inline', '((image) @img)')
    if not okq then
      image_lines = {}
      has_images = false
      clear_scroll_keys()
      return
    end

    local lines = {}
    for _, tree in ipairs(parser:parse()) do
      for _, node in query:iter_captures(tree:root(), bufnr, 0, -1) do
        local sr = node:range()  -- 0-based start row
        sr = sr + 1              -- 1-based
        lines[#lines + 1] = { line = sr, next = sr + 1 }
      end
    end

    image_lines = lines
    has_images = #lines > 0
    if has_images then set_scroll_keys() else clear_scroll_keys() end
  end

  local grp = api.nvim_create_augroup('md_img_scroll_' .. bufnr, { clear = true })
  api.nvim_create_autocmd({ 'BufEnter', 'TextChanged', 'TextChangedI', 'InsertLeave' }, {
    group = grp,
    buffer = bufnr,
    callback = update_image_lines,
  })

  update_image_lines()
end

return M

Now I’m down to just one remaining pain point with markdown files: when the render-markdown plugin renders tables, the editor’s soft wrap interferes and breaks the layout.

Dynamically toggling soft wrap based on cursor position doesn’t work well either—because when the cursor enters or leaves a table region, the entire table flickers due to the wrap state changing. Once the cursor leaves the table, soft wrap kicks in again and messes up the rendering.

What I’m planning to implement is this: enable soft wrap globally, but when render-markdown renders a table, it will only render a partial slice of the original table content—keeping it unwrapped, and refreshing horizontally based on cursor position.

Then, when the cursor enters a table region, soft wrap will be temporarily disabled—so the table stays unwrapped even in edit mode. This way, entering or leaving a table won’t cause any layout shift or visual jitter. That would basically give me a fully-featured markdown editor with WYSIWYG rendering, live preview, synchronized scrolling, and seamless editing.What matters most is that the behavior in preview and edit modes is absolutely identical—navigation, search, scrolling, everything works the same.

But to make render-markdown support partial table rendering under global soft wrap, I’d have to modify its source code—and I’ve never written a single line of Lua before! Thankfully, today’s AI is incredibly powerful. I just describe what I want and report bugs, and it gives me complete working code. Just wait for it!