Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/epilande/checkbox-cycle.nvim
✅ Effortlessly cycle through checkbox states in Neovim
https://github.com/epilande/checkbox-cycle.nvim
markdown neovim nvim
Last synced: 5 days ago
JSON representation
✅ Effortlessly cycle through checkbox states in Neovim
- Host: GitHub
- URL: https://github.com/epilande/checkbox-cycle.nvim
- Owner: epilande
- License: mit
- Created: 2024-09-14T07:12:51.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2024-09-22T07:34:13.000Z (about 2 months ago)
- Last Synced: 2024-10-29T23:13:16.420Z (19 days ago)
- Topics: markdown, neovim, nvim
- Language: Lua
- Homepage:
- Size: 21.5 KB
- Stars: 10
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
checkbox-cycle.nvim ✅
A Neovim plugin for cycling through checkbox states.
## ❓ Why?
Managing checkboxes in markdown files can be tedious, especially when working with to-do lists or task management in documents. Manually typing out or toggling between different checkbox states (unchecked, in-progress, checked, etc.) slows down your workflow. `checkbox-cycle.nvim` simplifies this by allowing you to effortlessly toggle and cycle through custom checkbox states, streamlining task management directly within Neovim.
## ✨ Features
- 🔄 Cycle through customizable checkbox states.
- 🤹 Support for multiple state cycles.
- ⌨️ Easy integration with keybindings.
- 🧘 Preserve indentation when cycling checkboxes.
- ☑️ Add checkboxes to lines that don't have them.
- 🌈 Visual mode support for cycling multiple checkboxes.
## 📦 Installation
Using [lazy.nvim](https://github.com/folke/lazy.nvim):
```lua
{
'epilande/checkbox-cycle.nvim',
ft = 'markdown',
-- Optional: Configuration
opts = {
-- Example: Custom states
states = { '[ ]', '[/]', '[x]', '[~]' },
},
-- Optional: Key mappings
keys = {
{
'',
'CheckboxCycleNext',
desc = 'Checkbox Next',
ft = { 'markdown' },
mode = { 'n', 'v' },
},
{
'',
'CheckboxCyclePrev',
desc = 'Checkbox Previous',
ft = { 'markdown' },
mode = { 'n', 'v' },
},
},
}
```
Recommended plugins to complement checkbox-cycle.nvim for custom checkboxes
### render-markdown.nvim
[`render-markdown.nvim`](https://github.com/MeanderingProgrammer/render-markdown.nvim) is a plugin that improves the visual rendering of Markdown files within Neovim.
Example config:
```lua
{
'MeanderingProgrammer/render-markdown.nvim',
dependencies = { 'nvim-treesitter/nvim-treesitter', 'echasnovski/mini.icons' },
opts = {
checkbox = {
custom = {
['in-progress'] = { raw = '[/]', rendered = '', highlight = 'RenderMarkdownWarn' },
urgent = { raw = '[!]', rendered = '', highlight = 'RenderMarkdownError' },
canceled = { raw = '[~]', rendered = '', highlight = 'RenderMarkdownError' },
todo = { raw = '[-]', rendered = '', highlight = 'Comment' },
forwarded = { raw = '[>]', rendered = '', highlight = 'RenderMarkdownHint' },
scheduled = { raw = '[<]', rendered = '', highlight = 'RenderMarkdownHint' },
info = { raw = '[i]', rendered = '', highlight = 'RenderMarkdownInfo' },
question = { raw = '[?]', rendered = '', highlight = 'RenderMarkdownWarn' },
idea = { raw = '[I]', rendered = '', highlight = 'RenderMarkdownWarn' },
pros = { raw = '[p]', rendered = '', highlight = 'RenderMarkdownSuccess' },
cons = { raw = '[c]', rendered = '', highlight = 'RenderMarkdownError' },
star = { raw = '[s]', rendered = '', highlight = 'RenderMarkdownWarn' },
f = { raw = '[f]', rendered = '', highlight = 'RenderMarkdownH2' },
},
},
},
}
```
### obsidian.nvim
If you're working with Obsidian vaults, [`obsidian.nvim`](https://github.com/epwalsh/obsidian.nvim) can be a great addition. While it's primarily designed for Obsidian-specific features, it also offers some Markdown enhancements.
Example config:
```lua
{
'epwalsh/obsidian.nvim',
version = '*',
lazy = true,
ft = 'markdown',
opts = {
ui = {
enable = true,
checkboxes = {
[' '] = { char = '', hl_group = 'Comment' }, -- Todo
['/'] = { char = '', hl_group = 'DiagnosticWarn' }, -- In-progress
['x'] = { char = '', hl_group = 'DiagnosticOk' }, -- Done
['!'] = { char = '', hl_group = 'DiagnosticError' }, -- Urgent
['~'] = { char = '', hl_group = 'ObsidianTilde' }, -- Canceled
['-'] = { char = '', hl_group = 'Comment' }, -- Skip
['>'] = { char = '', hl_group = 'DiagnosticHint' }, -- Forwarded
['<'] = { char = '', hl_group = 'DiagnosticHint' }, -- Scheduled
['i'] = { char = '', hl_group = 'DiagnosticInfo' }, -- Info
['?'] = { char = '', hl_group = 'DiagnosticWarn' }, -- Question
['I'] = { char = '', hl_group = 'DiagnosticWarn' }, -- Idea
['p'] = { char = '', hl_group = 'DiagnosticOk' }, -- Pros
['c'] = { char = '', hl_group = 'DiagnosticError' }, -- Cons
['s'] = { char = '', hl_group = 'DiagnosticWarn' }, -- Star
['f'] = { char = '', hl_group = 'ObsidianRightArrow' }, -- Fire
},
external_link_icon = { char = '', hl_group = 'ObsidianExtLinkIcon' },
},
},
}
```
## ⚙️ Configuration
The plugin comes with default settings, but you can customize it to fit your needs:
```lua
require('checkbox-cycle').setup({
states = {
{ '[ ]', '[x]', '[?]' },
{ '[!]', '[~]', '[-]' },
}
})
```
### Options
- `states`: A list of lists, where each inner list represents a cycle of checkbox states. You can define multiple cycles for different types of checkboxes.
Defaults
```lua
{
states = {
{ '[ ]', '[x]' },
}
}
```
## 🎮 Usage
The plugin provides two main functions:
1. `cycle_next(cycle_index)` - Cycle to the next checkbox state
2. `cycle_prev(cycle_index)` - Cycle to the previous checkbox state
Parameters:
- `cycle_index` (optional): Specifies which state cycle to use. If not provided, it defaults to the first cycle.
You can create keybindings for these functions or use the provided commands:
- `:CheckboxCycleNext` - Cycle to the next state
- `:CheckboxCyclePrev` - Cycle to the previous state
These commands work in both normal mode (for single lines) and visual mode (for multiple lines).
### Example Keybindings
This plugin does not provide any default keybindings, so you’ll need to add them manually to your Neovim configuration. Here’s an example:
```lua
vim.keymap.set({ 'n', 'v' }, '', 'CheckboxCycleNext', { noremap = true, silent = true })
vim.keymap.set({ 'n', 'v' }, '', 'CheckboxCyclePrev', { noremap = true, silent = true })
```
## 🔬 Advanced Usage
### Multiple State Cycles
You can define multiple state cycles and use them selectively:
```lua
require('checkbox-cycle').setup({
states = {
{ '[ ]', '[/]', '[x]' },
{ '[>]', '[<]' },
{ '[!]', '[~]', '[-]' },
}
})
```
To cycle through a specific state cycle, use the `cycle_next()` or `cycle_prev()` functions with an index:
```lua
require('checkbox-cycle').cycle_next(2) -- Uses the second cycle: { '- [>]', '- [<]' }
```
### Visual Mode
The plugin supports cycling checkboxes in visual mode. This allows you to select multiple lines and cycle their checkboxes all at once. Here's how it works:
1. Enter visual mode ('v' or 'V')
2. Select the lines containing the checkboxes you want to cycle
3. Use your keybinding or command to cycle the checkboxes
All selected checkboxes will cycle to their next or previous state, depending on the command used. This feature is particularly useful for managing large lists or updating the status of multiple tasks at once.
## 🛠️ API
The plugin exposes the following functions:
- `setup(opts)`: Configure the plugin with custom options
- `cycle_next(cycle_index)`: Cycle to the next checkbox state
- `cycle_prev(cycle_index)`: Cycle to the previous checkbox state