Merge pull request #65 from kaymmm/vimwiki-checkboxes

Vimwiki checkboxes

Author: dkarter

README.md

@@ -162,6 +162,74 @@ let g:bullets_renumber_on_change = 0
 " 3. third existing bullet [ no renumbering so this bullet remained `3` ]
 ```
 
+Enable/disable toggling parent and child checkboxes to indicate "completion" of child checkboxes:
+
+```vim
+let g:bullets_nested_checkboxes = 1 " default = 1
+" Example:
+" - [ ] first bullet
+"   - [ ] child bullet  [ type <leader>x ]
+"     - [ ] sub-child
+"   - [ ] child bullet
+" 
+" Result:
+" - [o] first bullet   [ <- indicates partial completion of sub-tasks ]
+"   - [X] child bullet
+"     - [X] sub-child  [ <- children get checked when parents get checked ]
+"   - [ ] child bullet
+```
+
+Define the checkbox markers to use to indicate unchecked, checked, and "partially" checked. When only two marker characters are defined, the use of partial completion markers will be disabled. If more than two markers are defined, each character between the first and last characters will be used to indicate a percentage of the child checkboxes that are checked. Each marker corresponds to 1/n, where n is the number of partial completion markers. By default, there are three partial completion markers, `.`, `o`, and `O`, corresponding to 33%, 66%, and up to but less than 100%, respectively. Note that unchecked (`[ ]`) and checked (`[x]` or `[X]`) statuses using the default markers are always valid, even if you set custom markers for unchecked and checked.
+
+```vim
+let g:bullets_checkbox_markers = ' .oOX'
+" Example:
+" - [o] parent bullet  [ <- `o` indicates 66% - 99% of children are checked ]
+"   - [ ] child bullet
+"   - [.] child bullet [ <- partial completions don't count as complete ]
+"     - [ ] sub-child bullet [ <- 1/4 of children checked so parent is `.` ]
+"     - [ ] sub-child bullet
+"     - [ ] sub-child bullet
+"     - [X] sub-child bullet
+"   - [X] child bullet
+"   - [X] child bullet
+"
+" You can use fancy markers:
+" let g:bullets_checkbox_markers = '✗○◐●✓'
+" - [✗] unchecked
+" - [○] partial
+"   - [✓] checked
+"   - [✗] unchecked
+"   - [✗] unchecked
+"   - [✗] unchecked
+```
+
+Define whether toggling partially complete checkboxes sets the checkbox to checked or unchecked:
+
+```vim
+" Example 1:
+let g:bullets_checkbox_partials_toggle = 1 " default = 1
+" - [o] partially checked  [ type <leader>x ]
+"   - [x] sub bullet
+"   - [ ] sub bullet
+" 
+" Result:
+" - [x] checked
+"   - [x] sub bullet
+"   - [x] sub bullet
+" 
+" Example 2:
+let g:bullets_checkbox_partials_toggle = 0
+" - [o] partially checked  [ type <leader>x ]
+"   - [x] sub bullet
+"   - [ ] sub bullet
+" 
+" Result:
+" - [ ] checked
+"   - [ ] sub bullet
+"   - [ ] sub bullet
+```
+
 # Mappings
 
 * Insert new bullet in INSERT mode: `<cr>` (Return key)
@@ -243,6 +311,7 @@ Capybara integration testing. ❤️
 - [x] change nested outline levels in visual mode
 - [x] support renumbering of alphabetical, roman numerals, and nested lists
 - [x] update documentation for nested bullets
+- [x] support nested bullets with child and partial completion
 - [ ] support for nested numerical bullets, e.g., 1. -> 1.1 -> 1.1.1, 1.1.2
 - [ ] add option to turn non-bullet lines into new bullets with `<C-t>`/`>>`/`>`
 

doc/bullets.txt

@@ -10,7 +10,7 @@ TABLE OF CONTENTS                         *bullets-toc*
 |bullets-configuration|            Configuration
 |bullets-insert-new-bullet|        Inserting Bullets
 |bullets-indenting|                Indenting Bullets
-|bullets-checkboxes|               Gfm Markdown Checkboxes
+|bullets-checkboxes|               Gfm/vimwiki Markdown Checkboxes
 |bullets-mappings|                 Mappings
 
 
@@ -28,7 +28,7 @@ types:
 - Hyphenated lists
 * Star (or bullet) lists
 + Plus (also bullet) lists
-- [ ] GFM markdown checkbox lists
+- [ ] GFM/vimwiki markdown checkbox lists
 1. Numeric lists
 2) or this style of numeric lists
 a. alphabetic lists
@@ -223,6 +223,57 @@ You can always manually renumber the current list or visual selection using
 `gN` in NORMAL or VISUAL mode.
 
 
+Toggle Parent and Child Checkboxes
+----------------------------------
+If a checkbox has child checkboxes, checking the checkbox will check all
+its children, and unchecking it will uncheck all its children. When toggling
+a child checkbox, the parent will be checked, unchecked, or marked with
+a partial completion marker (see |bullets-checkboxes|). You can disable this
+behavior using the following:
+
+  `let g:bullets_nested_checkboxes = 0`
+
+
+Checkbox Marker and Partial Completion Symbols
+----------------------------------------------
+In addition to the GFM markdown checkbox symbols, ` ` (unchecked) and `x`
+(checked), you can define and use custom marker symbols. You can also define
+and use marker symbols indicating partial completion of child checkboxes,
+like vimwiki syntax. By default, three symbols are defined for 1%-33% complete
+(`.`), 34%-66% complete (`o`), and 67%-99% complete (`O`), with 0% and 100%
+completion indicated by the unchecked and checked markers, respectively.
+
+The marker symbols are defined in a text string consisting of the sequential
+markers to use for unckecked (first character), partially checked (0+ middle
+characters), and checked (last character) statuses:
+
+  `let g:bullets_checkbox_markers = ' .oOX'`
+
+You can define fewer or more intermediate characters for partial completion,
+and the completion intervals will be adjusted accordingly.
+
+If you only define a checked and unchecked marker symbol, partial completion
+will be disabled:
+
+  `let g:bullets_checkbox_markers = ' X'`
+
+The standard GFM marker symbols for checked and unchecked (` ` and `x`) will
+always work for compatibility purposes, even when you use custom marker symbols.
+
+You can also use fancy marker symbols, for example:
+
+  `let g:bullets_checkbox_markers = '✗○◐●✓'`
+
+
+Toggling Partially Checked Checkboxes
+-------------------------------------
+You can define whether toggling a partially checked checkbox will result in it
+being marked checked (1, default) or unchecked (0):
+
+
+  `let g:bullets_checkbox_partials_toggle = 1`
+
+
 INSERTING BULLETS                           *bullets-insert-new-bullet*
 
 When a supported file type is opened (see |bullets-configuration|) you can start
@@ -249,13 +300,21 @@ To indent the current bullet to the left: from insert mode press <CTRL-d>.
 For more information `:h i_CTRL-T` and `:h i_CTRL-D`
 
 
-GFM MARKDOWN CHECKBOXES                     *bullets-checkboxes*
+GFM AND VIMWIKI MARKDOWN CHECKBOXES         *bullets-checkboxes*
+
+Bullets.vim supports checking and unchecking GFM- and vimwiki-style markdown
+checkboxes. While in normal mode, move over a checkbox list item (anywhere
+on the item) and use <leader>x to toggle the checkbox state.
 
-Bullets.vim supports checking and unchecking GFM markdown checkboxes. While in
-normal mode, move over a checkbox list item (anywhere on the item) and use
-<leader>x to toggle the checkbox state.
+Vimwiki-style checkboxes allow for marking a checkbox as partially complete
+based on how many of its child checkboxes are checked. Partially complete
+checkboxes can use different markers to indicate a relative percentage of
+completion. Vimwiki-style (partial completion) checkboxes can be disabled
+through the `g:bullets_checkbox_markers` configuration option (see
+|bullets-configuration|).
 
-There are also |bullets-commands| that you can use to to create your own mappings.
+There are also |bullets-commands| that you can use to to create your own
+mappings.
 
 
 MAPPINGS                                    *bullets-mappings*