Turn your todos ✅ into tadas 🎉.
Vim tada is a file syntax and tools for managing a simple todo list including a hierarchy and some metadata.
- Smart keymaps built for speed
- Toggle todo states with
<Space>
- Collapse todo's various levels with
<C-T>1
-<C-T>6
- Collapse topics with
<Enter>
- Toggle todo states with
- Customizable statuses, symbols, and colors
- Supports up to 6 levels of nested to-do's
- Global and file specific configuration
- Archive collapsible sections
Sometimes on solo projects, I have wanted an organized todo structure. But things like GitHub projects, Trello, Jira, etc. are all too complicated. Additionally, when it's just me, I wanted to not have to leave my vim editor in order to keep track of what I wanted to work on. So...vim-tada!
I may eventually add advanced opt-in functionality with labels, dates, and some GUI-ish features. Or maybe not.
Using your preferred package manager add dewyze/vim-tada
. For example, with
vim-plug:
Plug 'dewyze/vim-tada'
- Format
- Topics
- Todos
- Folds
- Metadata
- Archives
- Todo Pane
- Keymaps
- Configuration
- File Config
- Contributing
Vim tada will recognize files named Tadafile
or with the .tada
extension.
- Topics: Start with
-
and end with:
- This is a topic:
- Todo Items: Start with
- [ ]
followed by text- This is a todo item
- List Items: Start with
-
but do not end with:
- This is a list item
- Notes: Notes start with a
>
This is a note
- Metadata: Starts with
|
followed by one of:[@,^,$,&,#,!,?]
and:
- This is a topic followed by metadata: | @:alice,bob | ^:2022-04-01 | !:High
- Comment: Comments start with a
#
- # This is a comment
- Archive: Starts with a
=== Archive Title
line, followed by lines prefixed with=
=== My Archive = - This is an archived topic:
Topics are just headers. You can think of them as milestones, epics, or stories.
Or you can think of them as organizational folders. Or just as h1
, h2
, h3
.
They are just a way to organize todos and list items. They are indented by one
shiftwidth
level. I.e. if your shiftwidth
is 2, then a one space indent will
not register as a topic.
Topics also determine how folds work. See that section for more details.
Topics can also have metadata.
Note: Currently metadata does nothing. Eventually I hope for it to allow for some advanced features with sorting, displaying info, or developing an interactive UI.
Todos are the bread and butter of vim-tada! You can create a todo item by
pressing <C-Space>
. It will toggle a box with - [ ]
in your line.
If you want to toggle between todo states:
<space>
: Toggle between todo item states
You can configure todo statuses and symbols.
A todo style is a predetermined set of statuses and symbols:
unicode
(default):blank: [ ], in_progress: [•], done: [✔], flagged: [⚑]
ascii
(default):blank: [ ], in_progress: [-], done: [x], flagged: [o]
simple
(default):blank: [ ], done: [âś”]
markdown
(default):blank: [ ], done: [x]
You can just set the style and these will be the todo states.
let g:tada_todo_style = 'ascii'
Or via file specific configs:
@config.todo_style = 'ascii'
You can set the todo statuses to anything you want, and the symbols as well.
Via global config in a vimrc:
let g:tada_todo_statuses = ['planned', 'doing', 'complete']
let g:tada_todo_symbols = {'planned': ' ' , 'doing': '🛠️', 'complete': '✅' }
Or via a file specific configs:
@config.todo_statuses = ['planned', 'doing', 'complete']
@config.todo_symbols = {'planned': ' ' , 'doing': '🛠️', 'complete': '✅' }
NOTE: For now, the status names are not visible and serve no purpose. I think eventually they may be displayed or used in a some UI elements. NOTE: The first status in the array is considered the "default" for new todo items.
You can fold topics basic on the indent level of the topic. There are several shortcuts you can use:
<Enter>
in insert mode will, if on a topic, will collapse that topic.<C-T>#
where#
is a number1-6
will fold to various topic levels.<C-T>0
will unfold everything except an archive.<C-T>o
will completely open all folds for the topic under the cursor.<C-T>c
will close all folds for the line under the cursor.
These are just shortcuts on top of some existing vim fold commands, so if you know the vim fold commands, feel free to use those.
🚧🚧 UNDER CONSTRUCTION 🚧🚧
For now, metadata does nothing. Eventually it can/will be used to add some advanced functionality for sorting, shortcuts, or an advanced UI.
Metadata syntax is | <sym>:<val>
Possible symbols are:
?
: Status@
: Assignees (comma separated)^
: Start date (YYYY-MM-DD)$
: End date (YYYY-MM-DD)&
: External Link#
: Tags!
: Priority
If you complete a top level topic (or any topic) you can move it to an "archive" which is fancy for a folded section at the bottom of the file.
Highlight the lines you want to archive and type <C-T>a
.
This will move the lines to the bottom of the file, and add an archive header
===
if an archive does not exist.
NOTE: This does not change indentation, which is why I recommend only archiving top level topics.
The archive will stay closed at all fold levels, but can be toggled open with
<Enter>
.
You can quickly open a specified tada file with the pane open command.
<LocalLeader>td
will open the Tadafile
in a vertical split on the right.
This is the only tada command available outside of editing a tada file.
Default: Tadafile
Set the file that is opened by the tada todo pane. Another option could be
todo.tada
or anything that meets the format extension.
Default: right
Set the location for the tada todo pane.
Acceptable values: left, top, right, bottom
Default: <LocalLeader>td
Set the global keymap for opening a tada side pane.
Default: min([round(&columns * 0.33), 60])
(33% width of vim, or 60
columns whichever is the minimum).
Set the size for a tada side pane. Can be a number or a calculation.
The following maps are present in tada specific files:
<C-Space>
: to toggle adding/removing a todo box- [ ]
<C-H>
: to clear anything to the left of the cursor:
: on an empty line to dedent to a topic|
: on an empty line to convert it to metadata>
: on an empty line to convert it to a note
<C-Space>
to toggle adding/removing a todo box- [ ]
(
Goes to the previous topic)
Goes to the next topic{
Goes to the previous parent topic}
Goes to the next parent topic
Vim tada has a variety of configuration options below is a list of them all:
See todo styles for information on using pre-defined todo styles.
See configuring todos for information on configuring todo statuses and symbols.
Default: 1
By default, when pressing <Enter>
, o
, or O
, automatically insert the same
leading characters.
Default: 1
By default, when using folds, the summary line will sum todo items from children. If you are on a slower machine, this could be slow. Set this to 0 to turn this feature off.
Default: 1
This determines whether (
,)
,{
,}
are remapped in normal mode.
Default: <C-Space>
For both normal and insert mode, this will toggle a box - [ ]
on a line.
Default: <C-H>
In insert mode, this will clear everything to the left of the cursor.
Default: <C-T>
For folds and archives (and future features) this is the map prefix used.
Default: 0
Use this to turn off all the mappings for <Space>
, <C-T>
, <C-Space>
, <C-H>
.
Default: 1
By default, <Tab>
will indent list/todo items if they are empty.
Default: <Space>
Set the mapping to toggle between todo states.
You can configure the colors by overriding any of the following keys.
A color must be one of the following:
- A hex string beginning with
#
(for terminals that supportguifg
) - An integer (for terminals using
ctermfg
) - An array with [
<gui hex>
,<cterm int>
]
NOTE: if you override the todo key, you need to define all of the colors.
let red = ["#cc6666", 168]
let orange = ["#de935f", 173]
let yellow = ["#f0c674", 180]
let canary = ["#bfbc91", 179]
let green = ["#84b97c", 108]
let jade = ["#4bb1a7", 73]
let blue = ["#81a2be", 80]
let royal = ["#648cb4", 74]
let purple = ["#b294bb", 140]
let gray = ["#969896", 245]
let white = ["#ffffff", 255]
let g:tada_colors = {
\ "archive": gray,
\ "comment": gray,
\ "invalid_config": red,
\ "metadata": jade,
\ "note": canary,
\ "todo": {
\ "in_progress": yellow,
\ "done": green,
\ "flagged": red,
\ },
\ "topic": {
\ "1": purple,
\ "2": royal,
\ "3": orange,
\ "4": purple,
\ "5": royal,
\ "6": orange,
\ },
\ }
Sometimes you may want different statuses or symbols for a specific file. (Maybe the file is more complex or simple than your typical file). You can set file specific configurations. You can put this anywhere in your file.
NOTE: These must be one line long, they are not parsed if they are multiple lines.
# proj.tada
@config.todo_statuses = ['blank', 'done']
@config.todo_symbols = { 'blank': ' ', 'done': 'D' }
Available settings:
@config.todo_stasuses
: Array of strings@config.todo_symbols
: Hash with statuses as keys@config.todo_style
: One of:unicode
,ascii
,markdown
,simple
@config.colors
: Hash with string keys and hex/int/array colors. See colors
See CONTRIBUTING.md
See the final sections of the proj.tada:
- Fancy Todo Lists
- Project Collaboration
- UI Based