docs: add queue_sort and category_sort config fields (#100)
Problem: The queue view sort order (priority → due → order) is hardcoded with no documentation of a configurable alternative. Solution: Document `queue_sort` and `category_sort` config fields with named presets, sort key syntax, `-` direction prefix, and the `status` key opt-in for disabling the pending/done split. Update the views section to reference the new `pending-sort` tag.
This commit is contained in:
parent
c9471ebe90
commit
8780e5cffb
1 changed files with 55 additions and 3 deletions
|
|
@ -397,13 +397,15 @@ Category view (default): ~ *pending-view-category*
|
||||||
order tasks were added unless `category_order` is set (see
|
order tasks were added unless `category_order` is set (see
|
||||||
|pending-config|). Blank lines separate categories. Within each category,
|
|pending-config|). Blank lines separate categories. Within each category,
|
||||||
pending tasks appear before done tasks. Priority tasks (`!`) are sorted
|
pending tasks appear before done tasks. Priority tasks (`!`) are sorted
|
||||||
first within each group. Category sections are foldable with `zc` and
|
first within each group. The within-category sort order is configurable
|
||||||
`zo`.
|
via `category_sort` (see |pending-sort|). Category sections are foldable
|
||||||
|
with `zc` and `zo`.
|
||||||
|
|
||||||
Queue view: ~ *pending-view-queue*
|
Queue view: ~ *pending-view-queue*
|
||||||
A flat list of all tasks sorted by priority, then by due date (tasks
|
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
|
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
|
after all pending tasks. The sort order is configurable via `queue_sort`
|
||||||
|
(see |pending-sort|). Category names are shown as right-aligned virtual
|
||||||
text alongside the due date virtual text so tasks remain identifiable
|
text alongside the due date virtual text so tasks remain identifiable
|
||||||
across categories. The buffer is named `pending://queue`.
|
across categories. The buffer is named `pending://queue`.
|
||||||
|
|
||||||
|
|
@ -711,6 +713,56 @@ Fields: ~
|
||||||
given order. Categories not in the list are appended
|
given order. Categories not in the list are appended
|
||||||
after the ordered ones in their natural order.
|
after the ordered ones in their natural order.
|
||||||
|
|
||||||
|
{queue_sort} (string|string[], default: 'default') *pending-sort*
|
||||||
|
Sort order for the queue (priority) view. Accepts a
|
||||||
|
named preset string or an ordered list of sort keys.
|
||||||
|
|
||||||
|
Presets: ~
|
||||||
|
`'default'` priority → due → order → id
|
||||||
|
`'due-first'` due → priority → order → id
|
||||||
|
`'alphabetical'` description → priority → order → id
|
||||||
|
`'newest-first'` entry (desc) → priority → order → id
|
||||||
|
`'recent'` modified (desc) → priority → order → id
|
||||||
|
|
||||||
|
Sort keys: ~
|
||||||
|
`'priority'` Higher priority first (descending)
|
||||||
|
`'due'` Earlier due date first (nil last)
|
||||||
|
`'status'` Pending before done
|
||||||
|
`'category'` Alphabetical by category
|
||||||
|
`'description'` Alphabetical by task text
|
||||||
|
`'entry'` Oldest creation date first
|
||||||
|
`'modified'` Oldest modification first
|
||||||
|
`'order'` Internal insertion order
|
||||||
|
`'id'` Task creation order
|
||||||
|
|
||||||
|
Prefix a key with `-` to flip its default direction
|
||||||
|
(e.g. `'-due'` for latest-first). `'priority'`
|
||||||
|
defaults to descending; all other keys default to
|
||||||
|
ascending. Implicit `order`, `id` tiebreakers are
|
||||||
|
appended when absent for stable, deterministic sort.
|
||||||
|
|
||||||
|
When `'status'` appears in the key list, the
|
||||||
|
pending-before-done split is disabled and status
|
||||||
|
participates as a normal sort field. Otherwise
|
||||||
|
pending tasks always appear before done tasks.
|
||||||
|
|
||||||
|
Examples: >lua
|
||||||
|
vim.g.pending = { queue_sort = 'due-first' }
|
||||||
|
vim.g.pending = {
|
||||||
|
queue_sort = { 'priority', '-due', 'description' },
|
||||||
|
}
|
||||||
|
<
|
||||||
|
|
||||||
|
{category_sort} (string|string[], default: 'default')
|
||||||
|
Sort order for tasks within each category in
|
||||||
|
category view. Same syntax as `queue_sort`. The
|
||||||
|
`'default'` preset is priority → order → id.
|
||||||
|
Example: >lua
|
||||||
|
vim.g.pending = {
|
||||||
|
category_sort = { 'due', 'priority', 'order' },
|
||||||
|
}
|
||||||
|
<
|
||||||
|
|
||||||
{folding} (boolean|table, default: true) *pending.FoldingConfig*
|
{folding} (boolean|table, default: true) *pending.FoldingConfig*
|
||||||
Controls category-level folds in category view. When
|
Controls category-level folds in category view. When
|
||||||
`true`, folds are enabled with the default foldtext
|
`true`, folds are enabled with the default foldtext
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue