Merge develop branch (#166)

As part of v0.11 release

Author: bngarren

.gitignore

@@ -1,7 +1,6 @@
 vendor/plenary.nvim
 consolidated.md
 tests/fixtures
-tests/environments.lua
 
 logs/
 

Makefile

@@ -1,8 +1,13 @@
 .PHONY: test test-file test-interactive clean
 
+# allow `make test DEBUG=1` (or any other target) to export DEBUG=1
+DEBUG ?= 0
+ifeq ($(DEBUG),1)
+export DEBUG
+endif
+
 FILE ?= $(f)
 TEST ?= $(t)
-
 BASENAME := $(basename $(notdir $(FILE)))
 
 #    - If FILE is empty, leave FILE_PATH empty.

README.md

@@ -25,8 +25,9 @@ A Markdown-based todo/task plugin for Neovim.
 - Smart toggling behavior
 - Archive completed todos
 - Todo templates with LuaSnip snippet integration
-- 🆕 Custom todo states!
+- Custom todo states
   - More than just "checked" and "unchecked", e.g. "partial", "in-progress", "on-hold"
+- 🆕 Automatic todo creation (list continuation in insert mode)
 
 > [!NOTE]
 > Check out the [Wiki](https://github.com/bngarren/checkmate.nvim/wiki) for additional documentation and recipes, including:
@@ -42,7 +43,6 @@ A Markdown-based todo/task plugin for Neovim.
 <img width="1200" height="341" alt="checkmate_demo_complex" src="https://github.com/user-attachments/assets/8bbb9b20-23f7-4f82-b2b3-a8e8d2d9d4c5" />
 
 
-
 https://github.com/user-attachments/assets/d9b58e2c-24e2-4fd8-8d7f-557877a20218
 
 <!-- panvimdoc-ignore-start -->
@@ -158,7 +158,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 |--------------|-------------|
 | `archive` | Archive all checked todo items in the buffer. See api `archive()` |
 | `check` | Mark the todo item under the cursor as checked. See api `check()`|
-| `create` | Create a new todo item at the current line or line below if a todo already exists. In visual mode, convert each line to a todo item. See api `create()`|
+| `create` | In normal mode, converts the current line into a todo (or if already a todo, creates a sibling below). In visual mode, converts each selected line into a todo. In insert mode, creates a new todo on the next line and keeps you in insert mode. For more advanced placement, indentation, and state options, see the `create(opts)` API. |
 | `cycle_next` | Cycle a todo's state to the next available. See api `cycle()` |
 | `cycle_previous` | Cycle a todo's state to the previous. See api `cycle()` |
 | `lint` | Lint this buffer for Checkmate formatting issues. See api `lint()` |
@@ -168,6 +168,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 | `metadata remove` | Remove a specific metadata tag from the todo under the cursor or within the selection. Usage: `:Checkmate metadata remove <key>`. See api `remove_metadata(key)` |
 | `metadata select_value` | Select a value from the 'choices' option for the metadata tag under the cursor. See api `select_metadata_value()` |
 | `metadata toggle` | Toggle a metadata tag on/off for the todo under the cursor or within the selection. Usage: `:Checkmate metadata toggle <key> [value]`. See api `toggle_metadata(key, value)` |
+| `remove` | Convert a todo line back to regular text. See api `remove(opts)`. By default, will preserve the list item marker and remove any metadata. This can be configured via `opts`.
 | `remove_all_metadata` | Remove *all* metadata tags from the todo under the cursor or within the selection. See api `remove_all_metadata()` |
 | `toggle` | Toggle the todo item under the cursor (normal mode) or all todo items within the selection (visual mode). See api `toggle()`. This command only toggles between `unchecked` and `checked`. To change to custom states, use the api `toggle(target_state)` or the `cycle_*` commands. |
 | `uncheck` | Mark the todo item under the cursor as unchecked. See api `uncheck()` |
@@ -182,6 +183,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 <summary>Config definitions/annotations</summary>
 
 ```lua
+-----------------------------------------------------
 ---Checkmate configuration
 ---@class checkmate.Config
 ---
@@ -238,7 +240,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---
 ---The states that a todo item may have
 ---Default: "unchecked" and "checked"
----Note that Gith[118;1:3uub-flavored Markdown specification only includes "checked" and "unchecked".
+---Note that Github-flavored Markdown specification only includes "checked" and "unchecked".
 ---
 ---If you add additional states here, they may not work in other Markdown apps without special configuration.
 ---@field todo_states table<string, checkmate.TodoStateDefinition>
@@ -254,8 +256,15 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---@field style checkmate.StyleSettings?
 ---
 ---Enter insert mode after `:Checkmate create`, require("checkmate").create()
+---Default: true
 ---@field enter_insert_after_new boolean
 ---
+---List continuation refers to the automatic creation of new todo lines when insert mode keymaps are fired, i.e., typically <CR>
+---To offer optimal configurability and integration with other plugins, you can set the exact keymaps and their functions via the `keys` option. The list continuation functionality can also be toggled via the `enabled` option.
+--- - When enabled and keymap calls `create()`, it will create a new todo line, using the origin/current row with reasonable defaults
+--- - Works for both raw Markdown (e.g. `- [ ]`) and Unicode style (e.g. `- ☐`) todos.
+---@field list_continuation checkmate.ListContinuationSettings
+---
 ---Smart toggle provides intelligent parent-child todo state propagation
 ---
 ---When you change a todo's state, it can automatically update related todos based on their
@@ -275,14 +284,14 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---@field todo_count_position checkmate.TodoCountPosition
 ---
 ---Formatter function for displaying the todo count indicator
----@field todo_count_formatter fun(completed: integer, total: integer)?: string
+---@field todo_count_formatter? fun(completed: integer, total: integer): string
 ---
 ---Whether to count child todo items recursively in the todo_count
 ---If true, all nested todo items will count towards the parent todo's count
 ---@field todo_count_recursive boolean
 ---
----Whether to register keymappings defined in each metadata definition. If set the false,
----metadata actions need to be called programatically or otherwise mapped manually
+---Whether to register keymappings defined in each metadata definition.
+---When false, default metadata keymaps are not created; you can still call require('checkmate').toggle_metadata() or bind keys manually.
 ---@field use_metadata_keymaps boolean
 ---
 ---Custom @tag(value) fields that can be toggled on todo items
@@ -311,6 +320,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---@field level ("trace" | "debug" | "info" | "warn" | "error" | "fatal" | vim.log.levels.DEBUG | vim.log.levels.ERROR | vim.log.levels.INFO | vim.log.levels.TRACE | vim.log.levels.WARN)?
 ---
 --- Should print log output to a file
+--- Default: true
 ---@field use_file boolean
 ---
 --- The default path on-disk where log files will be written to.
@@ -324,16 +334,17 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 
 -----------------------------------------------------
 
+---The broad categories used internally that give semantic meaning to each todo state
 ---@alias checkmate.TodoStateType "incomplete" | "complete" | "inactive"
 
 ---@class checkmate.TodoStateDefinition
 ---
---- The text string used for a todo marker is expected to be 1 character length.
+--- The glyph or text string used for a todo marker is expected to be 1 character length.
 --- Multiple characters _may_ work but are not currently supported and could lead to unexpected results.
 ---@field marker string
 ---
 --- Markdown checkbox representation (custom states only)
---- For custom states, this determines how the todo state is written in Markdown syntax.
+--- For custom states, this determines how the todo state is written to file in Markdown syntax.
 --- Important:
 ---   - Must be unique among all todo states. If two states share the same Markdown representation, there will
 ---   be unpredictable behavior when parsing the Markdown into the Checkmate buffer
@@ -383,6 +394,42 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 
 -----------------------------------------------------
 
+---@class checkmate.ListContinuationSettings
+---
+--- Whether to enable list continuation behavior
+---
+--- Default: true
+---@field enabled? boolean
+---
+--- Control behavior when cursor is mid-line (not at the end).
+---
+--- When `true` (default):
+---   - Text after cursor moves to the new todo line
+---   - Original line is truncated at cursor position
+---   - Example: "- ☐ Buy |milk and eggs" → "- ☐ Buy" + "- ☐ milk and eggs"
+---
+--- When `false`:
+---   - List continuation only works when cursor is at end of line
+---
+--- Default: true
+---@field split_line? boolean
+---
+--- Define which keys trigger list continuation and their behavior.
+---
+--- Each key can map to either:
+---   - A function that creates the new todo
+---   - A table with `rhs` (function) and optional `desc` (description)
+---
+--- Default keys:
+---   - `<CR>`: Create sibling todo (same indentation)
+---   - `<S-CR>`: Create nested todo (indented as child)
+---
+--- **Important**: This field completely replaces the default keys (no merging).
+--- To keep some defaults while adding custom keys, explicitly include them in your config.
+---@field keys? table<string, {rhs: function, desc?: string}|function>
+---
+-----------------------------------------------------
+
 ---@class checkmate.SmartToggleSettings
 ---
 ---Whether to enable smart toggle behavior
@@ -476,7 +523,7 @@ The Checkmate buffer is **saved as regular Markdown** which means it's compatibl
 ---i.e. what is used after insertion
 ---@field get_value? checkmate.GetValueFn
 ---
----@alias checkmate.ChoicesFn fun(context?: checkmate.MetadataContext, cb?: fun(items: string[])): string[]?
+---@alias checkmate.ChoicesFn fun(context?: checkmate.MetadataContext, cb?: fun(items: string[])): string[]|nil
 ---
 ---Values that are populated during completion or select pickers
 ---Can be either:
@@ -613,6 +660,11 @@ return {
       desc = "Create todo item",
       modes = { "n", "v" },
     },
+    ["<leader>Tr"] = {
+      rhs = "<cmd>Checkmate remove<CR>",
+      desc = "Remove todo marker (convert to text)",
+      modes = { "n", "v" },
+    },
     ["<leader>TR"] = {
       rhs = "<cmd>Checkmate remove_all_metadata<CR>",
       desc = "Remove all metadata from a todo item",
@@ -655,6 +707,24 @@ return {
   },
   style = {}, -- override defaults
   enter_insert_after_new = true, -- Should enter INSERT mode after `:Checkmate create` (new todo)
+  list_continuation = {
+    enabled = true,
+    split_line = true,
+    keys = {
+      ["<CR>"] = function()
+        require("checkmate").create({
+          position = "below",
+          indent = false,
+        })
+      end,
+      ["<S-CR>"] = function()
+        require("checkmate").create({
+          position = "below",
+          indent = true,
+        })
+      end,
+    },
+  },
   smart_toggle = {
     enabled = true,
     include_cycle = false,
@@ -873,7 +943,6 @@ todo_states = {
 
 <img width="800" height="145" alt="checkmate_custom_states" src="https://github.com/user-attachments/assets/b8f89d00-4523-4106-8dbe-82059b1a1334" />
 
-
 #### State types
 States have three behavior types that affect smart toggle and todo counts:
 | Type | Behavior | Example States |
@@ -1009,11 +1078,13 @@ For in-depth guide and recipes for custom metadata, see the [Wiki](https://githu
 <a id="archiving"><a/>
 
 # ☑️ Archiving
-Allows you to easily reorganize the buffer by moving all checked/completed todo items to a Markdown section beneath all other content. The unchecked todos are reorganized up top and spacing is adjusted.
+Allows you to easily reorganize the buffer by moving all **completed** todo items to a Markdown section beneath all other content. The remaining unchecked/incomplete todos are reorganized up top and spacing is adjusted.
+
+Archiving collects all todos with the "completed" [state type](#state-types), which includes the default "checked" state, but possibly others based on custom todo states.
 
 See `Checkmate archive` command or `require("checkmate").archive()`
 
-> Current behavior (could be adjusted in the future): a checked todo item that is nested under an unchecked parent will not be archived. This prevents 'orphan' todos being separated from their parents. Similarly, a checked parent todo will carry all nested todos (checked and unchecked) when archived.
+> Current behavior (could be adjusted in the future): a completed todo item that is nested under an incomplete parent will not be archived. This prevents 'orphan' todos being separated from their parents. Similarly, a completed parent todo will carry all nested todos (completed and incomplete) when archived.
 
 #### Heading
 By default, a Markdown level 2 header (##) section named "**Archive**" is used. You can configure the archive section heading via `config.archive.heading`
@@ -1119,7 +1190,7 @@ Planned features:
 
 - [x] **Custom todo states** - support beyond binary "checked" and "unchecked", allowing for todos to be in custom states, e.g. pending, not-planned, on-hold, etc. _Added v0.10.0_
 
-- [ ] Sorting API - user can register custom sorting functions and keymap them so that sibling todo items can be reordered quickly. e.g. `function(todo_a, todo_b)` should return an integer, and where todo_a/todo_b is a table containing data such as checked state and metadata tag/values
+- [x] **List (todo) continuation** - automatically created new todo lines in insert mode, e.g. `<CR>` on a todo line will create a new todo below. _Added v0.11.0_
 
 <a id="contributing"><a/>