nvim-scissors ✂️

Automagical editing and creation of snippets.

add-new-snippet.mp4

edit-existing-snippet.mp4

Features
Rationale
Installation
Usage
Configuration
Note on JSON-formatting
Credits

Features

Add new snippets, edit snippets, delete snippets.
Syntax highlighting while you edit the snippet. Includes highlighting of tokens like $0 or ${2:foobar}.
Automagical conversion from buffer text to JSON string (quotes are escaped, etc.)
Intuitive UI for editing the snippet, dynamically adapting the number of prefixes.
Auto-reloading of the new/edited snippet (if using LuaSnip).
JSON-formatting and sorting of the snippet file after updating, using yq or jq. (Optional, but useful when version-controlling your snippet collection.)
Uses either telescope or vim.ui.select as pickers for snippet/file selection.
ℹ️ Supports only VSCode-style snippets.

Tip

You can use snippet-converter.nvim to convert your snippets to the VSCode format.

Rationale

Regrettably, there are innumerable formats in which snippets can be saved. The only format supported by several applications and thus the closest thing to a standard is the VSCode snippet format. For portability, and to future-proof your snippet collection, it can make sense to save your snippets in that format.
Most notably, the VSCode format is used by plugins like friendly-snippets and supported by LuaSnip.
However, the snippets are stored as JSON files, which are a pain to modify manually. This plugin aims to alleviate that pain by automagically writing the JSON for you.

Installation

Note

This plugin is only for editing and creating snippets. It does not expand snippets, which is done by snippet engines like LuaSnip.

-- lazy.nvim
{
	"chrisgrieser/nvim-scissors",
	-- dependencies = "nvim-telescope/telescope.nvim",
	opts = {
		snippetDir = "path/to/your/snippetFolder",
	} 
},

-- packer
use {
	"chrisgrieser/nvim-scissors",
	-- dependencies = "nvim-telescope/telescope.nvim",
	config = function()
		require("scissors").setup ({
			snippetDir = "path/to/your/snippetFolder",
		})
	end,
}

When telescope.nvim is installed, automatically uses it as picker. If not, falls back to vim.ui.select (which is customizable with plugins like dressing.nvim).

Usage

The plugin provides two commands, addNewSnippet and editSnippet. Here is the code to create keymaps for them:

vim.keymap.set(
	"n",
	"<leader>se",
	function() require("scissors").editSnippet() end
)

-- when used in visual mode, will prefill the dedented selected text as body
vim.keymap.set(
	{ "n", "x" },
	"<leader>sa",
	function() require("scissors").addNewSnippet() end
)

The popup intelligently adapts to changes in the prefix area. Each new line represents one prefix, and creating or removing lines thus changes the number of prefixes.

Configuration

The .setup() call is optional.

-- default settings
require("scissors").setup {
	snippetDir = vim.fn.stdpath("config") .. "/snippets",
	editSnippetPopup = {
		height = 0.4, -- relative to the window, between 0-1
		width = 0.6,
		border = "rounded",
		keymaps = {
			cancel = "q",
			saveChanges = "<CR>",
			goBackToSearch = "<BS>",
			delete = "<C-BS>",
			openInFile = "<C-o>",
			insertNextToken = "<C-t>", -- insert & normal mode
		},
	},
	-- `none` writes as a minified json file using `:h vim.encode.json`.
	-- `yq` and `jq` ensure formatted & sorted json files, which is relevant when
	-- you are version control your snippets.
	jsonFormatter = "none", -- "yq"|"jq"|"none"
}

Tip

vim.fn.stdpath("config") returns the path to your nvim config.

Note on JSON-formatting

This plugin writes JSON files via vim.encode.json. This method always writes the file in minified form, and also does not have a deterministic order of dictionary keys. That means that the JSON file can have a different order of keys before and after updating it via nvim-scissors.

Both, minification and unstable key order, are of course problem if you version-control your snippet collection. To solve this problem, nvim-scissors can optionally unminify and sort the JSON files via yq or jq after updating a snippet. (Both are also available via mason.nvim.)

It is recommended to run yq/jq once on all files in your snippet collection, since the first time you edit a file, you would still get a large diff from the initial sorting. You can do so with yq using this command:

cd "/your/snippet/dir"
fd ".*\.json" | xargs -I {} yq --inplace --output-format=json "sort_keys(..)" {}

How to do the same with jq is left as an exercise to the reader.

Credits

About Me
In my day job, I am a sociologist studying the social mechanisms underlying the digital economy. For my PhD project, I investigate the governance of the app economy and how software ecosystems manage the tension between innovation and compatibility. If you are interested in this subject, feel free to get in touch.

Blog
I also occasionally blog about vim: Nano Tips for Vim

Profiles

cleong14 / nvim-scissors