https://github.com/athar-qadri/scratchpad.nvim
Effortlessly manage scratchpads in Neovim
https://github.com/athar-qadri/scratchpad.nvim
lua neovim plugin
Last synced: 7 days ago
JSON representation
Effortlessly manage scratchpads in Neovim
- Host: GitHub
- URL: https://github.com/athar-qadri/scratchpad.nvim
- Owner: athar-qadri
- License: mit
- Created: 2024-12-31T17:59:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-03-06T10:46:21.000Z (about 1 month ago)
- Last Synced: 2025-03-06T11:36:48.638Z (about 1 month ago)
- Topics: lua, neovim, plugin
- Language: Lua
- Homepage:
- Size: 95.7 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neovim-sorted - athar-qadri/scratchpad.nvim
- awesome-neovim-sorted - athar-qadri/scratchpad.nvim
README
# scratchpad.nvim
`scratchpad.nvim` is a customizable and feature-rich Neovim plugin for managing and synchronizing scratchpad data. It provides a flexible configuration system, intuitive UI, and reliable data storage to streamline your development workflow.
**What makes `scratchpad.nvim` stand out?**
- **Floating Windows**: Scratchpads open in floating windows, eliminating the need for additional splits or buffers.
- **Push Data Seamlessly**: Push text from the current buffer (selected text or current line) directly to the scratchpad without opening it.
- **Automatic Filename Management**: Scratchpad filenames are handled internally, so you can focus on more important things.
https://github.com/user-attachments/assets/eddde5de-0fe7-42c2-b868-a682229f2c67
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Features
- **Customizable Configurations**: Easily extend and merge default configurations to suit your needs.
- **Data Synchronization**: Automatically save and sync scratchpad data with robust error handling.
- **Project Root Detection**: Supports a wide range of project identifiers for seamless integration.
## Installation
* neovim 0.8.0+ required
* install using your favorite plugin manager (i am using `lazy` in this case)
### Using [lazy.nvim](https://github.com/folke/lazy.nvim)
```lua
{
"athar-qadri/scratchpad.nvim",
event = "VeryLazy",
dependencies = { "nvim-lua/plenary.nvim" }, -- don't forget to add this one if you don't have it yet!
config = function()
require("scratchpad"):setup()
end,
}
```
### Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
```lua
use {
"athar-qadri/scratchpad.nvim",
requires = { "nvim-lua/plenary.nvim" },
config = function()
require("scratchpad"):setup()
end,
}
```
## Usage
### Setup
Initialize `scratchpad.nvim` with default settings or provide a custom configuration.
```lua
local scratchpad = require("scratchpad")
-- Default setup
scratchpad:setup()
--or
-- Custom setup
scratchpad:setup({
settings = {
sync_on_ui_close = true,
title = "My Scratch Pad"
},
default = {
--here you specify project root identifiers (Cargo.toml, package.json, blah-blah-blah)
--or let your man do the job
root_patterns = { ".git", "package.json", "README.md" },
},
})
```
### Keymap Configuration
You can set up custom key mappings for enhanced functionality. Below is an example keymap configuration:
```lua
{
keys = {
{
"es",
function()
local scratchpad = require("scratchpad")
scratchpad.ui:new_scratchpad()
end,
desc = "open scratchpad",
},
},
}
```
### Easy Setup Using Lazy
```lua
return {
"athar-qadri/scratchpad.nvim",
event = "VeryLazy",
opts = {},
dependencies = {
"nvim-lua/plenary.nvim",
},
config = function()
local scratchpad = require("scratchpad")
scratchpad:setup({ settings = { sync_on_ui_close = true } })
end,
keys = {
{
"es",
function()
local scratchpad = require("scratchpad")
scratchpad.ui:new_scratchpad()
end,
desc = "show scratch pad",
vim.keymap.set({ "n", "v" }, "ps", function()
local scratchpad = require("scratchpad")
scratchpad.ui:sync()
end, { desc = "Push selection / current line to scratchpad" }),
},
},
}
```
**Run the command `:Scratch` to open Scratchpad for your current project.**
**You can also directly push the data - `text selection` (visual mode) or `current line` (normal mode) to your scratchpad by pressing `ps` using above configuration.**
### Example Workflow
1. **Initialize a Scratchpad**:
The plugin detects your project root and initializes a scratchpad associated with the directory. If no project root is found, your current working directory will be consider for a unique scratchpad.
2. **Synchronize Data**:
Changes to the scratchpad are saved automatically based on your configuration. Your cursor position in scratchpad is saved even after the closing the ui.
3. **Customize Behavior**:
Modify setting `sync_on_ui_close` to control how data is managed.
## Configuration
Below is a detailed breakdown of the configuration options available:
### `ScratchpadConfig`
| Key | Description |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `sync_on_ui_close` | any time the ui menu is closed then the state of the scratchpad will be sync'd back to the fs. |
| `root_patterns` | Specify project root identifiers (e.g., .git, package.json).|
Refer to `config.lua` for more detailed options and comments.
## Contributing
We welcome contributions! Feel free to submit issues or pull requests to improve the plugin.
## License
This project is licensed under the MIT License. See the `LICENSE` file for more details.
## Acknowledgments
- Built with ❤️ using [Lua](https://www.lua.org/) and [Neovim](https://neovim.io/).
- Inspired by [Harpoon](https://github.com/ThePrimeagen/harpoon/tree/harpoon2).