README file from
GithubOrganise 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. Tasks with the same date are
ordered by priority (🔺 ⏫ 🔼 none 🔽 ⏬). Undated incomplete tasks
follow dated ones, in their original order. 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).[/]is in progress. - When the Tasks plugin
is installed, the type of each symbol in its core or custom status settings
overrides these defaults. For example,
[>]counts as cancelled when its type isCANCELLED, and[d]counts as done when its type isDONE, regardless of their names. Settings are read each time a command runs, so changes apply without reloading Organise Tasks. This also works when Tasks is disabled. - Dates use the Tasks plugin's emoji:
📅(or📆,🗓) due,⏳(or⌛) scheduled,🛫start,✅done and❌cancelled, each with or without a trailing variation selector. Dates are read on every checkbox, whatever its status 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. Plain bullets have no dates or priority. - 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.
- Sort date (due date, else scheduled): which date Sort by due date uses. Earliest of start, scheduled and due uses the earliest of the three, like the Tasks plugin's "happens" date.
- In-progress tasks first (off): in both sort commands, in-progress tasks go above other incomplete tasks. Each group keeps its own order.
- 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. With Earliest of start, scheduled and due, the earliest date within the range is used. 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
- Open Settings → Community plugins and select Browse.
- Search for Organise Tasks, then select Install and Enable.
BRAT
- Install and enable the BRAT plugin.
- Run BRAT: Add a beta plugin for testing and enter
ChrisDavison/organise-tasks. - Enable Organise Tasks in Settings → Community plugins.
Manual
- Download
main.jsandmanifest.jsonfrom the latest GitHub release. - Put both files in
<vault>/.obsidian/plugins/organise-tasks/. The folder name must match the plugin ID inmanifest.json. - 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.