From ad466434a7199084186bdd650a29e6458dd7e5ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20Harnes?= Date: Tue, 2 Apr 2024 16:21:24 +0200 Subject: [PATCH] docs: update vimdoc --- vimdoc.md | 276 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 200 insertions(+), 76 deletions(-) diff --git a/vimdoc.md b/vimdoc.md index c525455..39eb7b0 100644 --- a/vimdoc.md +++ b/vimdoc.md @@ -1,27 +1,32 @@ -# 📸 img-clip.nvim +# 📋 img-clip.nvim Effortlessly embed images into any markup language, like LaTeX, Markdown or Typst. -## Features +https://github.com/HakonHarnes/img-clip.nvim/assets/89907156/ab4edc10-d296-4532-bfce-6abdd4f218bf -- Paste images directly from the system clipboard. -- Drag and drop images from your web browser or file explorer to embed them. -- Embed images as files, URLs, or directly as Base64. -- Configurable templates with cursor positioning and figure labels. -- Default templates for widely-used markup languages like LaTeX, Markdown and Typst. -- Cross-compatibility with Linux, Windows, and MacOS. +## ⚡ Features -See these features in action in the [demonstration section](#demonstration)! +- 📋 Paste images directly from your system clipboard +- 🖱️ Seamlessly drag and drop images from your web browser or file explorer +- 📁 Embed images as files, web URLs, or Base64-encoded data +- 🌐 Automatically download and embed images from the web +- ⚙️ Process images using configurable shell commands +- 🎨 Configurable templates with placeholders for file paths, labels, and cursor positioning +- 📝 Built-in templates for popular markup languages like LaTeX, Markdown, and Typst +- 🔧 Extensive configuration options, including per-project, per-directory, and per-filetype settings +- 🔌 Powerful API with example integrations for popular plugins like [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) and [oil.nvim](https://github.com/stevearc/oil.nvim) +- 💻 Compatible with Linux, macOS, and Windows, including WSL! -## Requirements +## 🔧 Requirements -- **Linux:** [xclip](https://github.com/astrand/xclip) (x11) or [wl-clipboard](https://github.com/bugaevc/wl-clipboard) (wayland). -- **MacOS:** [pngpaste](https://github.com/jcsalterego/pngpaste) (optional, but recommended). -- **Windows:** No requirements. +- **Linux:** [xclip](https://github.com/astrand/xclip) (x11) or [wl-clipboard](https://github.com/bugaevc/wl-clipboard) (wayland) +- **MacOS:** [pngpaste](https://github.com/jcsalterego/pngpaste) (optional, but recommended) +- **Windows:** No additional requirements -> ⚠️ Run `:checkhealth img-clip` after installation to ensure requirements are satisfied. +> [!IMPORTANT] +> Run `:checkhealth img-clip` after installation to ensure requirements are satisfied. -## Installation +## 📦 Installation Install the plugin with your preferred package manager: @@ -30,87 +35,103 @@ Install the plugin with your preferred package manager: ```lua return { "HakonHarnes/img-clip.nvim", - event = "BufEnter", + event = "VeryLazy", opts = { -- add options here -- or leave it empty to use the default settings }, keys = { -- suggested keymap - { "p", "PasteImage", desc = "Paste clipboard image" }, + { "p", "PasteImage", desc = "Paste image from system clipboard" }, }, } ``` -## Usage +## 🚀 Usage ### Commands The plugin comes with the following commands: -- `PasteImage` Inserts the image from the clipboard into the document. +- `PasteImage`: Pastes an image form the system clipboard +- `ImgClipDebug`: Prints the debug log, including the output of shell commands +- `ImgClipConfig`: Prints the current configuration -Consider binding `PasteImage` to something like `p`. +> [!TIP] +> Consider binding `PasteImage` to something like `p`. ### API You can also use the Lua equivalent, which allows you to override your configuration by passing the options directly to the function: ```lua -require("img-clip").pasteImage({ use_absolute_path = false, file_name = "image.png" }) +require("img-clip").paste_image(opts?, input?) -- input is optional and can be a file path or URL ``` -## Configuration +
Example + +```lua +require("img-clip").paste_image({ use_absolute_path = false, file_name = "image.png" }, "/path/to/file.png") +``` + +
+ +## ⚙️ Configuration ### Setup -The plugin comes with the following defaults: +The plugin is highly configurable. Please refer to the default configuration below: ```lua { default = { - debug = false, -- enable debug mode - dir_path = "assets", -- directory path to save images to, can be relative (cwd or current file) or absolute - process_cmd = "", -- shell command to process the image before saving or embedding as base64 (e.g. "convert -quality 85 - -") - file_name = "%Y-%m-%d-%H-%M-%S", -- file name format (see lua.org/pil/22.1.html) - url_encode_path = false, -- encode spaces and special characters in file path - use_absolute_path = false, -- expands dir_path to an absolute path - relative_to_current_file = false, -- make dir_path relative to current file rather than the cwd - relative_template_path = true, -- make file path in the template relative to current file rather than the cwd - prompt_for_file_name = true, -- ask user for file name before saving, leave empty to use default - show_dir_path_in_prompt = false, -- show dir_path in prompt when prompting for file name - use_cursor_in_template = true, -- jump to cursor position in template after pasting - insert_mode_after_paste = true, -- enter insert mode after pasting the markup code - embed_image_as_base64 = false, -- paste image as base64 string instead of saving to file - max_base64_size = 10, -- max size of base64 string in KB - template = "$FILE_PATH", -- default template - copy_images = false, -- copy images instead of using the original file - download_images = true, -- download images and save them to dir_path instead of using the URL - + -- file and directory options + dir_path = "assets", ---@type string + file_name = "%Y-%m-%d-%H-%M-%S", ---@type string + use_absolute_path = false, ---@type boolean + relative_to_current_file = false, ---@type boolean + + -- template options + template = "$FILE_PATH", ---@type string + url_encode_path = false, ---@type boolean + relative_template_path = true, ---@type boolean + use_cursor_in_template = true, ---@type boolean + insert_mode_after_paste = true, ---@type boolean + + -- prompt options + prompt_for_file_name = true, ---@type boolean + show_dir_path_in_prompt = false, ---@type boolean + + -- base64 options + max_base64_size = 10, ---@type number + embed_image_as_base64 = false, ---@type boolean + + -- image options + process_cmd = "", ---@type string + copy_images = false, ---@type boolean + download_images = true, ---@type boolean + + -- drag and drop options drag_and_drop = { - enabled = true, -- enable drag and drop mode - insert_mode = false, -- enable drag and drop in insert mode + enabled = true, ---@type boolean + insert_mode = false, ---@type boolean }, }, -- filetype specific options - -- any options that are passed here will override the default config - -- for instance, setting use_absolute_path = true for markdown will - -- only enable that for this particular filetype - -- the key (e.g. "markdown") is the filetype (output of "set filetype?") filetypes = { markdown = { - url_encode_path = true, - template = "![$CURSOR]($FILE_PATH)", - download_images = false, + url_encode_path = true, ---@type boolean + template = "![$CURSOR]($FILE_PATH)", ---@type string + download_images = false, ---@type boolean }, html = { - template = '$CURSOR', + template = '$CURSOR', ---@type string }, tex = { - relative_template_path = false, + relative_template_path = false, ---@type boolean template = [[ \begin{figure}[h] \centering @@ -118,7 +139,7 @@ The plugin comes with the following defaults: \caption{$CURSOR} \label{fig:$LABEL} \end{figure} - ]], + ]], ---@type string }, typst = { @@ -127,7 +148,7 @@ The plugin comes with the following defaults: image("$FILE_PATH", width: 80%), caption: [$CURSOR], ) - ]], + ]], ---@type string }, rst = { @@ -135,11 +156,11 @@ The plugin comes with the following defaults: .. image:: $FILE_PATH :alt: $CURSOR :width: 80% - ]], + ]], ---@type string }, asciidoc = { - template = 'image::$FILE_PATH[width=80%, alt="$CURSOR"]', + template = 'image::$FILE_PATH[width=80%, alt="$CURSOR"]', ---@type string }, org = { @@ -149,21 +170,24 @@ The plugin comes with the following defaults: #+CAPTION: $CURSOR #+NAME: fig:$LABEL #+END_FIGURE - ]=], + ]=], ---@type string }, }, - -- override options for specific files, dirs or custom triggers - files = {}, -- file specific options (e.g. "main.md" or "/path/to/main.md") - dirs = {}, -- dir specific options (e.g. "project" or "/home/user/project") - custom = {}, -- custom options enabled with the trigger option + -- file, directory, and custom triggered options + files = {}, ---@type table + dirs = {}, ---@type table + custom = {}, ---@type table } ``` ### Options Option values can be configured as either static values (e.g. "assets"), or by dynamically generating them through functions. -For instance, to set the `dir_path` to match the name of the currently opened file: + +
Example: Dynamically set the dir path + +To set the `dir_path` to match the name of the currently opened file: ```lua dir_path = function() @@ -171,11 +195,13 @@ dir_path = function() end, ``` +
+ ### Processing images The `process_cmd` option allows you to specify a shell command to process the image before saving or embedding it as base64. The command should read the image data from the standard input and write the processed data to the standard output. -Examples: +
Example: ImageMagick ```bash process_cmd = "convert - -quality 85 -" -- compress the image with 85% quality @@ -185,31 +211,37 @@ process_cmd = "convert - -colorspace Gray -" -- convert the image to grayscale Ensure the specified command and its dependencies are installed and accessible in your system's shell environment. The above examples require [ImageMagick](https://imagemagick.org/index.php) to be installed. +
+ ### Filetypes Filetype specific options will override the default (or global) configuration. Any option can be specified for a specific filetype. -For instance, if you only want to use absolute file paths for LaTeX, then: +Filetype specific options are determined by the _filetype_ (see `:help filetype`). +You can override settings for any filetype by specifying it as the key in your configuration: ```lua filetypes = { - tex = { - use_absolute_path = true + = { -- obtained from "set filetype?" + -- add options here } } ``` -Filetype specific options are determined by the _filetype_ (see `:help filetype`). -You can override settings for any filetype by specifying it as the key in your configuration: +
Example: LaTeX-specific configuration + +If you only want to use absolute file paths for LaTeX, then: ```lua filetypes = { - = { -- obtained from "set filetype?" - -- add options here + tex = { + use_absolute_path = true } } ``` +
+ ### Overriding options for specific files, directories or custom triggers Options can be overridden for specific files, directories or based on custom conditions. @@ -227,7 +259,7 @@ The plugin evaluates the options in the following order: 4. Filetype specific options 5. Default options -Example configuration: +
Example ```lua -- file specific options @@ -250,7 +282,7 @@ dirs = { -- custom options custom = { { - trigger = function() -- returns true to activate + trigger = function() -- returns true to enable return vim.fn.strftime("%A") == "Monday" end, template = "Template for Mondays only", @@ -280,6 +312,8 @@ dirs = { } ``` +
+ ### Project-specific settings with the `.img-clip.lua` file Project-specific settings can be specified in a `.img-clip.lua` file in the root of your project. @@ -294,7 +328,7 @@ return { } ``` -Example: +
Example ```lua return { @@ -310,6 +344,8 @@ return { } ``` +
+ ### Templates Templates in the plugin use placeholders that are dynamically replaced with the correct values at runtime. @@ -323,7 +359,9 @@ For available placeholders, see the following table and the [demonstration](#dem | `$LABEL` | Figure label, generated from the file name, converted to lower-case and with spaces replaced by dashes. | `the-image` (from `the image.png`) | | `$CURSOR` | Indicates where the cursor will be placed after insertion if `use_cursor_in_template` is true. | | -Templates can also be defined using functions with the above placeholders available as function parameters: +Templates can also be defined using functions with the above placeholders available as function parameters. + +
Example ```lua template = function(context) @@ -331,10 +369,12 @@ template = function(context) end ``` -## Drag and drop +
+ +## 🖱️ Drag and drop The drag and drop feature enables users to drag images from the web browser or file explorer into the terminal to automatically embed them, in normal mode. -It can be optionally enabled in insert mode using the `drag_and_drop.insert_mode` option. +Drag and drop can also be enabled in insert mode by setting the `drag_and_drop.insert_mode` option to `true`. For drag and drop to work properly, the following is required by the terminal emulator: 1. The terminal emulator must paste the file path or URL to the image when it is dropped into the terminal. @@ -363,3 +403,87 @@ A list of terminal emulators and their capabilities is given below. _\*If you're having issues on Windows, try changing the default shell to `powershell` or `pwsh`. See `:h shell-powershell`._ _\*MacOS URLs only work in Safari._ + +## 🔌 Integrations + +### Telescope.nvim + +The plugin can be integrated with [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) to provide a seamless way to select and embed images using Telescope's powerful fuzzy finding capabilities. + +
Example configuration + +```lua +function() + local telescope = require("telescope.builtin") + local actions = require("telescope.actions") + local action_state = require("telescope.actions.state") + + telescope.find_files({ + attach_mappings = function(_, map) + local function embed_image(prompt_bufnr) + local entry = action_state.get_selected_entry() + local filepath = entry[1] + actions.close(prompt_bufnr) + + local img_clip = require("img-clip") + img_clip.paste_image(nil, filepath) + end + + map("i", "", embed_image) + map("n", "", embed_image) + + return true + end, + }) +end +``` + +The above function should be bound to a keymap, e.g. through lazy.nvim. + +
+ +### Oil.nvim + +The plugin also integrates with [oil.nvim](https://github.com/stevearc/oil.nvim), providing a convenient way to browse and select images using Oil's file explorer. + +
Example configuration + +```lua +function() + local oil = require("oil") + local filename = oil.get_cursor_entry().name + local dir = oil.get_current_dir() + oil.close() + + local img_clip = require("img-clip") + img_clip.paste_image({}, dir .. filename) +end +``` + +The above function should be bound to a keymap, e.g. through lazy.nvim. + +
+ +Alternatively, you can invoke img-clip.nvim directly from your oil.nvim configuration: + +
Example configuration + +```lua +keymaps = { + ["p"] = function() + local oil = require("oil") + local filename = oil.get_cursor_entry().name + local dir = oil.get_current_dir() + oil.close() + + local img_clip = require("img-clip") + img_clip.paste_image({}, dir .. filename) + end, +} +``` + +
+ +## 🙌 Contributing + +Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue on the GitHub repository.