Organise Tasks

An Obsidian plugin with four commands: Sort completed tasks to bottom, Sort by due date, Clear completed tasks, and Clear completed tasks in current document. In the command palette they appear as Organise Tasks: Sort completed tasks to bottom and so on.

It reorders the task list at the level your cursor is on, or at the shallowest list level touched by your selection. Completed tasks sink to the bottom and everything else keeps its order.

Sort by due date orders incomplete tasks soonest first using 📅 due dates, falling back to ⏳ scheduled dates. Undated incomplete tasks follow dated ones. Completed tasks move to the bottom using the completed-task sorting rules described below. Overdue tasks are not specially grouped or highlighted. You can optionally limit sorting to dates within a number of days from today.

Clear completed tasks removes [x] / [X] items at the same list level and within the same cursor or selection scope as sorting. Children and annotations are removed with their parent, including unfinished children. Cancelled items are kept by default. The edit can be undone in one step.

Clear completed tasks in current document applies the same clearing rules to every list in the active document, including nested tasks. When a completed parent is removed, its whole subtree is removed with it.

Behaviour

• A completed task is [x] / [X] (done) or [-] (cancelled).
• When the Tasks plugin is installed, symbols with type CANCELLED in its core or custom status settings also count as cancelled. For example, [>] counts as cancelled when its type is CANCELLED, regardless of its name. Settings are read each time a command runs, so changes apply without reloading Organise Tasks. This also works when Tasks is disabled. Without Tasks installed, [-] remains the only cancelled symbol.
• Done tasks come first in the completed group, cancelled tasks after them.
• Within each completed group, tasks are ordered newest first by their done (✅ YYYY-MM-DD) or cancelled (❌ YYYY-MM-DD) date. Tasks without a date follow the dated ones, in their original order.
• Everything else at the sorted level counts as incomplete and stays on top. This includes [ ], [/], other status symbols, and plain bullets.
• Children and annotation lines move with their parent and keep their order.
• No selection: the cursor item's own level. With a selection: the shallowest list level present, and every affected parent's full child list is sorted.
• One blank line keeps a list together; two consecutive blank lines break it.
• Tasks inside blockquotes and callouts are supported. Quote-depth changes, quoted titles, paragraphs, and fenced code bound the list being sorted.
• The cursor follows its task after a sort. With a selection, it moves to the first selected task. A single undo reverses the sort.

These are the defaults. Settings → Organise Tasks can adjust the rules below without changing any of the above until you touch a setting.

Settings

• Cancelled counts as completed (on): cancelled tasks are completed and sink below done tasks. Off: cancelled tasks count as incomplete and stay on top.
• Clear cancelled tasks (off): also remove cancelled items when clearing completed tasks. This is independent of Cancelled counts as completed.
• Require complete trees before clearing (off): keep a completed parent when any child list item cannot be cleared. The command reports blocked trees while continuing to clear other complete trees and individual tasks.
• Clear complete siblings in blocked trees (off): when the complete-tree requirement blocks a parent, still remove fully complete child task trees.
• Tab width (4): how many columns a tab character counts for when measuring list indentation. Matters when lists mix tabs and spaces.
• Undated completed tasks (bottom of the completed group): completed tasks without a date follow the dated ones. Top: they come first.
• Sortable date range (days) (blank): blank sorts all dates as before. Set a whole number of days (0-365000) to sort incomplete tasks dated on or before today plus that many calendar days, including overdue dates. For example, with 60 days set on January 1, January and February dates are sortable, but June dates are not. A due date beyond the range falls back to a scheduled date within the range. Tasks with neither date in range join undated tasks after dated tasks, preserving their relative order. This setting only affects Sort by due date, not Sort completed tasks to bottom. The command's notice counts tasks excluded from date sorting because every date they have is beyond the range, even when nothing changes in the note. Tasks using an in-range scheduled-date fallback are not counted.

Installation

Community plugins

1. Open Settings → Community plugins and select Browse.
2. Search for Organise Tasks, then select Install and Enable.

BRAT

1. Install and enable the BRAT plugin.
2. Run BRAT: Add a beta plugin for testing and enter ChrisDavison/organise-tasks.
3. Enable Organise Tasks in Settings → Community plugins.

Manual

1. Download main.js and manifest.json from the latest GitHub release.
2. Put both files in <vault>/.obsidian/plugins/organise-tasks/. The folder name must match the plugin ID in manifest.json.
3. Enable Organise Tasks in Settings → Community plugins.

Upgrading from Todo Sorting

Version 2.0.0 changed the plugin ID from todo-sort-completed to organise-tasks. Install Organise Tasks, copy data.json from .obsidian/plugins/todo-sort-completed/ into .obsidian/plugins/organise-tasks/ to keep your settings, rebind any hotkeys, then remove the old plugin.

Usage

Run Sort completed tasks to bottom from the command palette, or bind a hotkey to it. Run Sort by due date to order incomplete tasks by their due or scheduled date. The two clear commands remove completed tasks from the current list scope or the whole active document.

Development

There is no build step and no dependencies. main.js is the complete source. Run the tests with node --test.

Scope

Not handled: ordered lists and multiple cursors. Those are reported rather than edited.

License

This project is licensed under the MIT License. See LICENSE for the full license text.