Get Things Done in plain ol’ Markdown.

Getting Things Down provides smart folding and TODO keyword highlighting for Markdown files, taking advantage of the heading outline structure inherent to Markdown (via HTML). Collapse/expand headings and list items, view overall progress, and jump to your project’s TODO file with a single mapping.

There are lots of vim plugin managers out there. I like vim-plug.

Most of Getting Things Down’s functionality comes automatically in the form of folding and syntax highlighting. If you can write documents in Markdown, you’re already 90% of the way there.

To take full advantage of its capabilities, simply make thoughtful use of headings when structuring your document, and pepper it with TODO annotations in list items and/or headings. Thus, the document below

-     Jake’s Bar Mitzvah
|     ================================================================================
|     
|-    ## Supplies
||    
||-   ### Food & Drink
|||   
|||     * DONE catering (Szechwan Palace)
|||     * TODO buy grape juice
|||   
||-   ### Equipment
|||   
|||-    * WAIT folding chairs & tables
||||
||||      may be provided by venue?
||||
|||     * DONE PA system
||    
|-    ## People
||    
||      * WIP  practice group dance routine
||-     * HELP hire a DJ
||| 
|||       NO rap music
||    
|-    ## Resources
||    
||      * http://chabad.org/library/article_cdo/aid/136670/jewish/Jewish-Prayers.htm
||      * http://szechwanpalace.com
|
-     Jewish Movie Night
|     ================================================================================
|     ...

can be collapsed like so:

-     Jake’s Bar Mitzvah
|     ================================================================================
|     
|-    ## Supplies
||    
||+   --- # Food & Drink -------------------------------- 50% [##########..........] -
||+   --- # Equipment ----------------------------------- 50% [##########..........] -
||    
|-    ## People
||    
||      * WIP  practice group dance routine
||+   - * HELP hire a DJ ------------------------------------------------------- [1] -
||    
|-    ## Resources
||    
||      * http://chabad.org/library/article_cdo/aid/136670/jewish/Jewish-Prayers.htm
||      * http://szechwanpalace.com
|
-     Jewish Movie Night
|     ================================================================================
|     ...

Note how the collapsed “Food & Drink” and “Equipment” lines display a progress bar on the right. This is automatically generated according to what portion of the tasks within the fold are marked DONE. Note also that the “HELP Hire a DJ” foldtext does not display a progress bar. Since there are no tasks inside of that fold, it reports the number of non-blank lines, instead.

As you continue to collapse the folds, the progress bars are recalculated to reflect the overall progress of all tasks they contain:

-     Jake’s Bar Mitzvah
|     ================================================================================
|     
|+    - # Supplies -------------------------------------- 50% [##########..........] -
|+    - # People ----------------------------------------- 0% [....................] -
|+    - # Resources ------------------------------------------------------------ [2] -
|
-     Jewish Movie Night
|     ================================================================================
|     ...

If you’re not familiar with folding, check out the help docs:

:h Folding

Getting Things Down recognizes five TODO keywords:

• TODO
• WIP (work-in-progress)
• DONE
• HELP (for when I’m stuck and need to study/analyze/ask for help)
• WAIT (requires someone else’s approval/contribution)

You can cycle between select keywords with <LocalLeader>c as long as the cursor is on the same line as the task.

<LocalLeader><LocalLeader> switches between the current file and its project-wide TODO file. This works for any file in any project, as long as there is a TODO.md file located somewhere within the project root.

Getting Things Down attempts to find the project-wide TODO file by walking up the current file’s path and recursively searching each directory along the way.

To change the default behavior of Getting Things Down, modify the lines below and add them to your .vimrc. (For booleans, 0 is falsy; any other number is truthy.)

" Defines the TODO keywords that `<LocalLeader>m` will cycle through.
let g:gtdown_cycle_states = ['DONE', 'WIP ', 'WAIT', 'HELP', 'TODO']

" Default fold level for new Markdown buffers (see `:h 'foldlevel'`).
let g:gtdown_default_fold_level = 2

" Should multi-line list items collapse too, or only headings?
let g:gtdown_fold_list_items = 1

" Display progress bar for folded headings/list items?
let g:gtdown_show_progress = 1

A buffer-local b:gtdown_show_progress value will override the global setting. For instance, the following autocommand will enable progress previews only for files named TODO.md:

let g:gtdown_show_progress = 0
augroup gtDown
  autocmd!
  autocmd BufReadPre TODO.md let b:gtdown_show_progress = 1
augroup END

The lines below set mappings for Getting Things Down’s major shortcuts.

" Quick-switch between current file and `TODO.md` of project root
nnoremap <LocalLeader><LocalLeader> :call getting_things_down#show_todo()<CR>

" Cycle through TODO keywords
nnoremap <silent> <LocalLeader>c :call getting_things_down#cycle_status()<CR>

I use <Leader><Leader> and <Leader>c, but it’d probably clobber someone else’s settings if those were the default.

The MIT License (MIT)

Copyright © 2017 Ryan Lue