⚜️Lspmark.nvim

A Sane[^1] Project-wise[^2] Bookmarks Plugin with Persistent[^3] Storage Based on LSP[^4] for Neovim.

Important: 🚧 This plugin is being developed in progress so breaking changes are expected. Breaking changes will be documented in CHANGELOG.md, check this document if you encounter any issues after updating.

Notice:

1. If you find any error log reported please try to remove the folder containing persistent files first (on Linux it is ~/.local/share/nvim/lspmark/) since during the development the internal representation of bookmarks may changed. :-)
2. Bookmark operations (toggle, modify comment, open telescope, etc.) on modified buffer will be slower, so saving the buffer before performing such operations is a good habit.

There is a bunch of bookmark plugins but none of them suit my demand, if you also finding a bookmark plugin that can:

1. Organize the bookmarks in project-wise since in most of my time I open Neovim in a project (cwd) and jump here and there,
2. Persistent the bookmarks across different Neovim launches.
3. Try to lay the bookmarks in the right place even after a format.
4. Can be deleted and pasted to other place, even not current file.
5. Use telescope to browse, jump or delete all the bookmarks.
6. Add comments to bookmarks for better searching.
7. Organize the bookmarks per git branch automatically.
8. …

Then not only the bookmarks, but also you, are in the right place. Let me show you the features one by one:

Features

Setup & Usage

First, install it using your favorite plugin manager and run the following code after installation:

require("lspmark").setup()
require("telescope").load_extension("lspmark")

Note: To open the telescope window, you can run Telescope lspmark, to delete current selection in the telescope picker, you can press d.

Second, you need to bind your keys (or assiociate some commands) to the following APIs to enable partial or all the features:

require('lspmark.bookmarks').paste_text()

This function is used for pasting texts deleted with bookmarks, you can bind the key to paste text (p) to it.

require('lspmark.bookmarks').toggle_bookmark({with_comment=false})

This function is used for toggling the bookmark at current line, you can bind the key to toggle the mark.

You can change with_comment to true to give you a prompt asking for comment each time when you creating a bookmark.

require('lspmark.bookmarks').delete_visual_selection()

This function is used for deleting the selection with bookmarks in visual mode, you can bind the key to delete text in visual mode (d) to it.

require('lspmark.bookmarks').delete_line()

This function is used for deleting one line with a bookmark in normal mode, you can bind the key to delete line in normal mode (dd) to it.

require('lspmark.bookmarks').modify_comment()

This function is used for modifying the comment for the bookmark under the cursor.

require('lspmark.bookmarks').show_comment()

This function is used for showing the entire content for the bookmark under the cursor.

Third, Call the following code:

-- <new_dir> can be nil, by default it is cwd.
require("lspmark.bookmarks").load_bookmarks(<new_dir>)

when you switch to a new cwd. Alternatively, you can define the following autocmd:

vim.api.nvim_create_autocmd({ "DirChanged" }, {
    callback = require("lspmark.bookmarks").load_bookmarks,
    pattern = { "*" },
})

Highlights

LspMark: The highlight group for the sign at left side.

LspMarkComment: The highlight group for the virtual text of the comment.

For Developers

There are a bunch of comments along with the codes, so it shouldn't be difficult to understand the code. The following concepts in the comments should be clarified:

• Mark: It is an abstract concept that means the line you want to put the mark.
• Sign: It means the sign displayed at the left of each line marked.
• Symbol: An LSP symbol covers a range of codes, it may have multiple marks in different offsets.
• Offset: A mark's offset relative to the start of a symbol.

FAQ

Known Issues

[^1]: "Sane" means it will try best to respect your intuition. [^2]: "Project-wise" means the bookmarks are organized according to the cwd (project). [^3]: "Persistent" means the bookmarks will be saved to file so they won't be lost when nvim is opened next time. [^4]: "LSP" means we store each bookmark's information associated with their LSP symbol.