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: about 23 hours 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 (13 days ago)
- Default Branch: main
- Last Pushed: 2024-09-22T07:34:13.000Z (5 days ago)
- Last Synced: 2024-09-23T03:04:23.771Z (5 days ago)
- Topics: markdown, neovim, nvim
- Language: Lua
- Homepage:
- Size: 21.5 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- 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