img-clip.nvim

The plugin supports granular overrides. Options are evaluated in the following order of precedence (highest to lowest):

1. Custom options: Based on a trigger function.
2. File specific options: Based on absolute path or filename.
3. Directory specific options: Based on absolute path.
4. Filetype specific options: Based on the buffer's filetype.
5. Default options: The global configuration.

Options can be nested. For example, you can define filetype-specific settings inside a directory-specific block.

-- file specific options
files = {
  ["/path/to/specific/file.md"] = {
    template = "Custom template for this file",
  },
  ["README.md"] = {
    template = "Custom template for README.md",
  },
},

-- directory specific options
dirs = {
  ["/path/to/project"] = {
    template = "Project specific template",

    filetypes = {
      markdown = {
        template = "markdown template"
      }
    },

    files = {
      ["readme.md"] = {
        dir_path = "images"
      },
    },
  },
},

-- custom options
custom = {
  {
    trigger = function()
      return vim.fn.strftime("%A") == "Monday"
    end,
    template = "Template for Mondays only",
  },
}

You can drag images from a web browser or file explorer directly into your terminal to automatically embed them in Neovim while in normal mode.

To enable drag and drop in insert mode, set the drag_and_drop.insert_mode option to true in your configuration.

Terminal Requirements

For drag and drop to function, your terminal emulator must:

1. Paste the file path or URL of the image when dropped.
2. Support bracketed paste mode so Neovim can distinguish pasted text from typed text.

Terminal Compatibility Summary

• Kitty: Supports Files and URLs on X11 and Wayland/macOS.
• Alacritty: Supports Files on X11 and macOS.
• Foot: Supports Files and URLs on Wayland.
• Windows Terminal: Supports Files and URLs on Windows.
• iTerm.app / Terminal.app: Support Files and URLs on macOS.
• Konsole: Supports Files and URLs on X11.

Troubleshooting

• Windows: If drag and drop fails, try changing your default shell to powershell or pwsh (see :h shell-powershell).
• macOS: Image URLs are only supported when using Safari.

The drag and drop feature allows you to drag images from a web browser or file explorer into the terminal to automatically embed them. By default, this works in Normal mode. To enable it in Insert mode, set the drag_and_drop.insert_mode option to true in your configuration.

Terminal Requirements

For drag and drop to function, your terminal emulator must:

1. Paste the file path or URL of the image when dropped.
2. Support bracketed paste mode so Neovim can distinguish pasted text from typed text.

Terminal Compatibility Summary

Note: MacOS URLs only work in Safari. If having issues on Windows, try using powershell or pwsh as your default shell.

-- Example configuration to enable drag and drop in insert mode
require("img-clip").setup({
  drag_and_drop = {
    insert_mode = true,
  },
})

The plugin is highly configurable using a Lua table. You can provide static values or dynamic functions for most options. Configuration can be applied globally (default), per filetype, per file, per directory, or via custom triggers.

{
  default = {
    -- file and directory options
    dir_path = "assets",
    extension = "png",
    file_name = "%Y-%m-%d-%H-%M-%S",
    use_absolute_path = false,
    relative_to_current_file = false,

    -- logging options
    verbose = true,

    -- template options
    template = "$FILE_PATH",
    url_encode_path = false,
    relative_template_path = true,
    use_cursor_in_template = true,
    insert_mode_after_paste = true,
    insert_template_after_cursor = true,

    -- prompt options
    prompt_for_file_name = true,
    show_dir_path_in_prompt = false,

    -- base64 options
    max_base64_size = 10,
    embed_image_as_base64 = false,

    -- image options
    process_cmd = "",
    copy_images = false,
    download_images = true,
    formats = { "jpeg", "jpg", "png" },

    -- drag and drop options
    drag_and_drop = {
      enabled = true,
      insert_mode = false,
    },
  },

  filetypes = {
    markdown = {
      url_encode_path = true,
      template = "![$CURSOR]($FILE_PATH)",
      download_images = false,
    },
    -- ... other filetypes
  },

  files = {},
  dirs = {},
  custom = {},
}