docs: document wip and blocked task states (#99) (#106)

Problem: The vimdoc only describes `pending`/`done`/`deleted` statuses
with no mention of work-in-progress or blocked states.

Solution: Document new `wip` and `blocked` statuses across views (sort
order), filters (new predicates), icons (`>` and `=`), highlight groups
(`PendingWip`, `PendingBlocked`), and the data format schema.
This commit is contained in:
Barrett Ruth 2026-03-08 19:13:57 -04:00 committed by GitHub
parent 36a469e964
commit e534e869a8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -413,14 +413,14 @@ Category view (default): ~ *pending-view-category*
Tasks are grouped under their category header. Categories appear in the
order tasks were added unless `category_order` is set (see
|pending-config|). Blank lines separate categories. Within each category,
pending tasks appear before done tasks. Priority tasks (`!`) are sorted
first within each group. Category sections are foldable with `zc` and
`zo`.
tasks are sorted by status (wip → pending → blocked → done), then by
priority, then by insertion order. Category sections are foldable with
`zc` and `zo`.
Queue view: ~ *pending-view-queue*
A flat list of all tasks sorted by priority, then by due date (tasks
without a due date sort last), then by internal order. Done tasks appear
after all pending tasks. Category names are shown as right-aligned virtual
A flat list of all tasks sorted by status (wip → pending → blocked →
done), then by priority, then by due date (tasks without a due date sort
last), then by internal order. Category names are shown as right-aligned virtual
text alongside the due date virtual text so tasks remain identifiable
across categories. The buffer is named `pending://queue`.
@ -452,6 +452,10 @@ Available predicates: ~
`priority` Show only tasks with priority > 0 (the `!` marker).
`wip` Show only tasks with status `wip` (work in progress).
`blocked` Show only tasks with status `blocked`.
`clear` Special value for |:Pending-filter| — clears the active filter
and shows all tasks.
@ -779,14 +783,16 @@ Fields: ~
{icons} (table) *pending.Icons*
Icon characters displayed in the buffer. The
{pending}, {done}, and {priority} characters
appear inside brackets (`[icon]`) as an overlay
on the checkbox. The {category} character
prefixes both header lines and EOL category
labels. Fields:
{pending}, {done}, {priority}, {wip}, and
{blocked} characters appear inside brackets
(`[icon]`) as an overlay on the checkbox. The
{category} character prefixes both header lines
and EOL category labels. Fields:
{pending} Pending task character. Default: ' '
{done} Done task character. Default: 'x'
{priority} Priority task character. Default: '!'
{wip} Work-in-progress character. Default: '>'
{blocked} Blocked task character. Default: '='
{due} Due date prefix. Default: '.'
{recur} Recurrence prefix. Default: '~'
{category} Category prefix. Default: '#'
@ -835,6 +841,14 @@ PendingOverdue Applied to the due date virtual text of overdue tasks.
PendingDone Applied to the text of completed tasks.
Default: links to `Comment`.
*PendingWip*
PendingWip Applied to the checkbox icon of work-in-progress tasks.
Default: links to `DiagnosticInfo`.
*PendingBlocked*
PendingBlocked Applied to the checkbox icon and text of blocked tasks.
Default: links to `DiagnosticError`.
*PendingPriority*
PendingPriority Applied to the `! ` priority marker on priority tasks.
Default: links to `DiagnosticWarn`.
@ -1200,7 +1214,8 @@ Schema: >
Task fields: ~
{id} (integer) Unique, auto-incrementing task identifier.
{description} (string) Task text as shown in the buffer.
{status} (string) `'pending'`, `'done'`, or `'deleted'`.
{status} (string) `'pending'`, `'wip'`, `'blocked'`, `'done'`,
or `'deleted'`.
{category} (string) Category name. Defaults to `default_category`.
{priority} (integer) `1` for priority tasks, `0` otherwise.
{due} (string) ISO date string `YYYY-MM-DD`, or absent.