codesnap.nvim/README.md

CodeSnap.nvim

📸 Snapshot plugin with rich features that can make pretty code snapshots for Neovim

• 🚣Migration
• ✨Features
• Prerequirements
• Install
  • Compile from source
  • Compile on ARM
  • Keymappings
  • Windows Support
• Usage
  • Copy into the clipboard
    • Copy into clipboard on Linux Wayland
  • Save the snapshot
  • Highlight code block
    • How to use
  • Take ASCII snapshot
  • Specify language extension
• Breadcrumbs
  • Show workspace in breadcrumbs
  • Custom path separator
• Line number
• Custom background
  • Solid color background
  • Customize background padding
• Watermark
• Commands
• Configuration
• Contribution
  • Contributors
• License

🚣Migration

If you have installed v0.x before, this chapter will show you what break changes version v1.x introduced.

• The CodeSnapPreviewOn command is not supported, if you prefer live-preview, you can pin CodeSnap.nvim version to v0.0.11 to continue using this command.
• The opacity and preview_title config has been removed from v1.0.0
• The editor_font_family was renamed to code_font_family

v1.x has a different architecture and better performance than v0.x, and v1.x can generate screenshots directly without an open browser. We recommend you upgrade to v1.x for a better experience.

✨Features

• 🤩 Beautiful code snap template
• 😎 Custom watermark and window style
• 💻 Beautiful Mac-style title bar
• 🤖 Generate snapshots using only a single command
• 🍞 Breadcrumbs for display file path
• 🌊 More beautiful background theme
• 🔢 Support for display line number make sharing code snapshot easier
• 🔆 Highlight specific lines of code
• 🖨️ Generate ASCII art code snapshots

Prerequirements

• Neovim 0.9.0+

Install

We recommend using Lazy.nvim to install CodeSnap.nvim, but you can still use another plugin manager you prefer.

Lazy.nvim

{ "mistricky/codesnap.nvim", build = "make" },

Packer

use {'mistricky/codesnap.nvim', run = 'make'}

Vim-Plug

Plug 'mistricky/codesnap.nvim', { 'do': 'make' }

It's worth mentioning that the screenshot feature is implemented by a module called generator written in Rust, when make the project, the CodeSnap.nvim will mount a precompiled cross-compile generator shared file into the plugin that depends on what OS you are using.

We precompiled the following targets:

• x86_64-unknown-linux-gnu
• x86_64-apple-darwin
• aarch64-apple-darwin

If your platform is in the above list, you can just run make after the plugin is installed like the above examples do, CodeSnap.nvim will automatically mount the shared file into the plugin. This means you don't need any Rust utils to compile manually from source.

Compile from source

You need to install Rust development environment before compiling from source, you can refer Install Rust for more detail.

Please keep in mind, cross-compile to these platforms only helps a portion of users to have out-of-box experience, if your platform is not in the above targets list, you still need to compile from source using make build_generator, for instance using Lazy:

{ "mistricky/codesnap.nvim", build = "make build_generator" },

We always recommend you to compile CodeSnap.nvim from source instead of using the precompiled shared file, because the correctness and consistency of compiling from source are always higher than cross-compiling.

Compile on ARM

If you try to compile CodeSnap.nvim on ARM architecture, you may need to install additional dependencies to compile it, thanks @matteocavestri mentioned in https://github.com/mistricky/codesnap.nvim/issues/53#issuecomment-2032088162

export CC=gcc
sudo dnf install libuv libuv-devel # On RHEL based systems
sudo apt-get install libtool libuv1-dev # On Debian based systems

Keymappings

If you use Lazy.nvim as your package manager, here are some examples show you how to configure keymappings for CodeSnap:

{
  "mistricky/codesnap.nvim",
  build = "make build_generator",
  keys = {
    { "<leader>cc", "<cmd>CodeSnap<cr>", mode = "x", desc = "Save selected code snapshot into clipboard" },
    { "<leader>cs", "<cmd>CodeSnapSave<cr>", mode = "x", desc = "Save selected code snapshot in ~/Pictures" },
  },
  opts = {
    save_path = "~/Pictures",
    has_breadcrumbs = true,
    bg_theme = "bamboo",
  },
}

Windows Support

Unfortunately, CodeSnap does not support Windows yet, but version v0.0.x is working fine on Windows. If you want to use CodeSnap on Windows, we recommend you pin the version to 0.0.11 to use CodeSnap, follow to 0.0.11 Document for more detail.

Usage

CodeSnap.nvim provides the following two ways to take snapshots of currently selected code

Copy into the clipboard

To take a beautiful snapshot use CodeSnap.nvim, you can just use CodeSnap command to generate a snapshot of the current selected code, then the CodeSnap.nvim will write the snapshot into the clipboard, and you can paste it anywhere you want.

https://github.com/mistricky/codesnap.nvim/assets/22574136/99be72db-57d7-4839-91d0-2a9dfb1901ac

Copy into clipboard on Linux Wayland

Copy screenshots directly into the clipboard is cool, however, it doesn't work well on wl-clipboard, because the wl-clipboard can't paste the content which come from exited processes. As Hyprland document say:

When we copy something on Wayland (using wl-clipboard) and close the application we copied from, the copied data disappears from the clipboard and we cannot paste it anymore. So to fix this problem we can use a program called as wl-clip-persist which will preserve the data in the clipboard after the application is closed.

If you using CodeSnap.nvim on wl-clipboard, you can refer wl-clip-persist, it reads all the clipboard data into memory and then overwrites the clipboard with the data from our memory to persist copied data.

Save the snapshot

Of course, you can use CodeSnapSave command to save the snapshot to path where you defined it in config.save_path

require("codesnap").setup({
  -- The save_path must be ends with .png, unless when you specified a directory path,
  -- CodeSnap will append an auto-generated filename to the specified directory path
  -- For example:
  -- save_path = "~/Pictures"
  -- parsed: "~/Pictures/CodeSnap_y-m-d_at_h:m:s.png"
  -- save_path = "~/Pictures/foo.png"
  -- parsed: "~/Pictures/foo.png"
  save_path = ...
})

https://github.com/mistricky/codesnap.nvim/assets/22574136/69b27e77-3dce-4bc3-8516-89ce636fe02d

Highlight code block

CodeSnap allows you to take code snapshots with highlights code blocks, we provide two commands for this scenario:

CodeSnapHighlight # Take code snapshot with highlights code blocks and copy it into the clipboard
CodeSnapSaveHighlight # Take code snapshot with highlights code blocks and save it somewhere

How to use

For take a code snapshot with highlights code blocks and save it somewhere. First you need to select code which you want to snapshot, then enter the command CodeSnapSaveHighlight to open a window show you the selected code which from previous step, now you can select code which you want to highlight, finally press the Enter key, CodeSnap will generate a snapshot with highlight blocks and save it in save_path.

Here is an example video:

https://github.com/mistricky/codesnap.nvim/assets/22574136/bea0bf6c-8fc9-4d09-9cab-4e1e6f47899c

Take ASCII snapshot

Run CodeSnapASCII, CodeSnap will generate a "code snapshot" in ASCII format and then copy it into clipboard automatically, it's really cool and lightweight, if you want to share your code in somewhere like Markdown document, even you can enjoy the code highlighting which provided by Markdown parser. Here is an usage video:

https://github.com/mistricky/codesnap.nvim/assets/22574136/91bc3d96-7dbd-4e1c-9224-95428c7cca48

Specify language extension

In some scenarios, CodeSnap.nvim cannot auto-detect what language syntax should used to highlight code, for example, shell script can have no extension, they specify interpreters using shebang.

CodeSnap.nvim won't read the whole content of the file, thus cannot detect what language syntax is this, in this case, you can specify extension explicitly, for instance:

CodeSnapSave sh
CodeSnap sh

Breadcrumbs

Breadcrumbs are something to display the current snapshot file path, you can open it through config has_breadcrumbs:

require("codesnap").setup({
  -- ...
  has_breadcrumbs = true
})

The breadcrumbs look like:

Show workspace in breadcrumbs

Breadcrumbs hide the workspace name by default, if you want to display workspace in breadcrumbs, you can just set show_workspace as true.

require("codesnap").setup({
  -- ...
  has_breadcrumbs = true
  show_workspace = true
})

Custom path separator

The CodeSnap.nvim uses / as the separator of the file path by default, of course, you can specify any symbol you prefer as the custom separator:

require("codesnap").setup({
  -- ...
  has_breadcrumbs = true
  breadcrumbs_separator = "👉"
})

Line number

We also support displaying line number, you can set has_line_number to true to display line number.

require("codesnap").setup({
  // ...
	has_line_number = true,
})

Custom background

The CodeSnap.nvim comes with many beautiful backgrounds preset, you can set any background you like by setting bg_theme to its name, just like:

require("codesnap").setup({
  -- The "default" background is one you see at the beginning of the README
  bg_theme = "default"
})

bamboo	sea
peach	grape
dusk	summer

Solid color background

If you prefer solid color background, you can set bg_color to your preferred color. For example:

require("codesnap").setup({
  -- ...
  bg_color = "#535c68"
})

Customize background padding

CodeSnap allows you to customize the padding of background using bg_x_padding, bg_y_padding and bg_padding, the default value is:

require("codesnap").setup({
  bg_x_padding = 122,
  bg_y_padding = 82,
  bg_padding = nil
})

If you want to hide background, you can set bg_padding to 0 in your config:

require("codesnap").setup({
  -- ...
  bg_padding = 0
})

Watermark

Watermark is something that makes screenshots more personalized, but if you don't like watermark just set it as an empty string to hide it.

require("codesnap").setup({
  -- ...
  watermark = ""
})

Commands

CodeSnap # Take a snapshot of the currently selected code and copy the snapshot into the clipboard

CodeSnapSave # Save the snapshot of the currently selected code and save it on the disk

CodeSnapASCII # Take a code snapshot in ASCII format

Lua

local codesnap <const> = require("codesnap")

-- Take a snapshot of the currently selected code and copy the snapshot into the clipboard
codesnap.copy_into_clipboard()

-- Save the snapshot of the currently selected code and save it on the disk
codesnap.save_snapshot()

Configuration

Define your custom config using setup function

require("codesnap").setup({...})

There is a default config:

{
    mac_window_bar = true,
    title = "CodeSnap.nvim",
    code_font_family = "CaskaydiaCove Nerd Font",
    watermark_font_family = "Pacifico",
    watermark = "CodeSnap.nvim",
    bg_theme = "default",
    breadcrumbs_separator = "/",
    has_breadcrumbs = false,
    has_line_number = false,
    show_workspace = false,
    min_width = 0,
    bg_x_padding = 122,
    bg_y_padding = 82,
    save_path = os.getenv("XDG_PICTURES_DIR") or (os.getenv("HOME").. "/Pictures")
}

Contribution

CodeSnap.nvim is a project that will be maintained for the long term, and we always accepts new contributors, please feel free to submit PR & issues.

The commit message convention of this project is following commitlint-wizardoc.

Contributors

Thanks to all contributors for their contributions and works they have done.

License

MIT.